## Welcome to XMLPartner Professional

Thank you for licensing XMLPartner Professional 2.5 from TurboPower Software Company. This file describes last minute information about XMLPartner Professional, including changes that were made after the printed documentation went to press. Be sure to review the material in this file before contacting TurboPower technical support.

> Installing XMLPartner Professional
> Uninstalling XMLPartner Professional
> What's New in Version 2.53
> TurboPower Package Naming Conventions
> Additions/Changes to the Manual
> Known Limitations
> Online Resources

### Installing XMLPartner Professional

Before starting the installation process, it is highly recommended that you close any running applications (especially compilers supported by XMLPartner Professional). It is also recommended that XMLPartner Professional be installed as root. Insert the TurboPower Product Suite CD and run the BrowseCD.sh shell script. The BrowseCD.sh program will run automatically if your system supports autorun CDs. If not, run BrowseCD.sh from the root folder of the CDROM. Follow the instructions presented by the program. This application is a shell program that will allow you to install any/all TurboPower products that you have purchased. Select XMLPartner in the listbox, and click on "Install Product" at the bottom of the screen. The XMLPartner Professional SETUP program will be launched. The installation will install XMLPartner Professional in the /usr/local/turbopower/xmlpartnerpro directory by default. You can specify a different directory if desired. Symbolic links to the XMLPartner Professional packages will be created in the kylix/bin directory.

The directory tree of an installation where all options are selected will look similar to this:

    /usr/local/turbopower/xmlpartnerpro/
      +---sources
      |   +---Examples
      |       +---Kylix
      |           +---xmldocs
      |           +---EXMLPro
      +---packages
      +---Help
          +---html

The XMLPartner Professional sources folder contains the XMLPartner Professional source files, compiled packages, and README.HTML (this file). The xmldocs folder contains sample XML documents for use with the EXml XML editor contained in the XMLEdit folder.

The Installation will attempt to automatically install components and help for Kylix. This is only done for the user that runs the installation. For other users you will want to use the manual method of installing the components. Be sure to check whether XMLPartner Professional's components are installed before proceeding with any manual installation methods.

In the event components and help are not automatically installed, you can install them manually by selecting Component | Install Packages on the IDE's main menu, press the '"Add" button, and browse for the correct XMLPartner Professional design time package. The package should be in the main XMLPartner Professional folder, and a symbolic link to it can be found in the kylix/bin directory. The name of the package should be bpltpxproXXXd.so (where XXX is the version number, i.e. 252 for version 2.52). See TurboPower Package Naming Conventions for a complete description of the TurboPower package naming scheme).

Top

### Uninstalling XMLPartner Professional

You can use the following steps to manually remove XMLPartner Professional from your system.

1. Uninstall the packages from the IDE.
2. As root, execute the xprouninstall.sh script in the XMLPartner Professional directory.

Top

### What's New In Version 2.53

This section lists the changes and enhancements incorporated into XMLPartner Professional 2.53 for those users upgrading from XMLPartner 2.52 or earlier.

Enhancements

- Added a BaseURI property to the TXpNode class.

- Added events to the TXpObjModel component and the TXpDocument class so that the XPath engine could have work performed by an external XSL processor. The new events include OnCurrentNode, OnFormatNumber, OnKeyLookup, OnResolveDocument, andOnVariableLookup.

- Added a StripWhitespaceNodes method to class TXpElement.

- Added an IsWhitespaceNode function to TXpText.

Bug fixes

Made minor corrections to the XPath engine.
970 - Parser adds invalid character to end of entity reference values
975 - If error occurs when parsing an external entity, the external entity's file is not closed
976 - Empty entity reference seen as parsing error
977 - When TXpParser.RaiseErrors is False, the error messages do not identify the file in which the error occurred
979 - Entity references not resolved properly in element content spec
980 - " within attribute value treated as attribute value delimiter
1002 - DOM: Attributes not written when call TXpObjModel.SaveToxxx from ISAPI DLL
1016 - Null attribute should not be ignored by TXpElement.SetAttribute

Top

### TurboPower Package Naming Conventions

XMLPartner Professional installs design-time and run-time packages that are named according to TurboPower conventions:

TurboPower changes package names with each new library release. Doing so prevents conflicts with applications built using run-time packages from some other version, as well as ensuring that you are using the latest version.

TurboPower's current package naming conventions are as follows:

- The first three characters, bpl, identify the package as a borland package.
- The next two characters, tp, identify this as a TurboPower package.
- This is followed by the short name of the product.
- The next three digits are the product version number (e.g., 253 for version 2.53)
- The next letter identifies the package as run-time or design-time (i.e., r or d)
- The remainder of the name indicates that the package is a shared object (.so) and the version number of the object.

Top

### Additions/Changes to the Manual

This topic lists the differences (e.g., enhancements, discrepancies) between the source code and the documentation. The differences are categorized by component and topic.

Chapter 6 Changes
Formatting objects
TXpElement class
TXpFilterBase class
TXpFilterHTML class
TXpFilterText class
TXpFilterXML class
TXpNode class
TXpNodeList class
TXpObjModel class
TXpParser component
TXpText class
TXpValue class (new)
TXpXSLProcessor component
XSLT elements

### Chapter 6 Changes

Using Variables, p. 236

The example template references a variable within its match attribute. This is not allowed as per the XSLT 1.0 specification. The Sale3.xsl stylesheet within the Examples\xmldocs folder illustrates the correct way to carry out the task.

Top

### Formatting Object Changes

The table-related formatting objects are documented in the manual but they are not implemented in this release of XMLPartner Professional. The table-related formatting objects are as follows:

- table
- table-body
- table-cell
- table-column
- table-row

space-after & space-before, p. 456

The manual does not list the sub-properties applicable to these properties. For more information, see Sections 7.9.6 and 7.9.5, respectively, of the XSL 1.0 specification at http://www.w3.org/TR/xsl/slice7.html#space-before.

Top

### TXpElement Changes

New method GetAttributeInt:

TXpElement.GetAttributeInt method

function GetAttributeInt(const sName : DOMString) : Integer;

=> Retrieves an attribute value as an integer.

Use this method to retrieve an attribute's value as an integer. If the value cannot be converted to an integer then an exception is raised.

See also: GetAttribute, GetAttributeNode, GetAttributeNodeNS, GetAttributeNS

TXpElement.SetAttributeNode, p. 172

The manual states "This method returns the attribute that was added to the element." Instead, it should state the following:

If the element already contains an attribute bearing the same name as the attribute referenced by parameter oNewAttr then this method returns the existing attribute. Otherwise this method returns the value nil.

TXpElement.SetAttributeNodeNS, p. 173

The manual states "This method returns the attribute that was added to the element." Instead, it should state the following:

If the element already contains an attribute bearing the same name as the attribute referenced by parameter oNewAttr then this method returns the existing attribute. Otherwise this method returns the value nil.

New method StripWhitespaceNodes:

TXpElement.StripWhitespaceNodes method

procedure StripWhitespaceNodes(bDeep : Boolean);

=> Strips the whitespace-only text nodes from an element.

Use this method to remove whitespace-only text nodes from an element. If the NormalizeData property of the TXpDocument class is set to True then the TXpObjModel component automatically strips whitespace nodes as the document is loaded. Whitespace is defined as a contiguous sequence of the characters #9 (tab), #10 (linefeed), #13 (carriage return), and #20 (space). Whitespace-only nodes contain only those characters defined as whitespace characters. If a text node contains any other character then it is not considered a whitespace node.

If parameter bDeep has the value False, only the element's immediate whitespace-only text nodes are stripped. If parameter bDeep has the value is True, this method strips whitespace-only text nodes from the element and its descendant elements.

See also: TXpText.IsWhitespaceNode

Top

### TXpFilterBase Changes

TXpFilterBase.XslProcessorFormatObjectEnd, p. 270

The Object Pascal declaration of this event is now as follows:

XSLProcessorFormatObjectEnd virtual method

procedure XslProcessorFormatObjectEnd(Sender : TObject); virtual;

=> Defines an event handler that is called after a formatting object is processed.

This is the event handler for the XSL processor's OnFormatObjectEnd event. Sender is the XSL processor raising the event. This method is called after the XSL processor has finished processing a formatting object and its child elements.

See also: XSLProcessorFormatObject

TXpFilterBase.XslProcessorFOProperty, p. 269

This method no longer exists. The transfer of formatting objects to a filter has been made more efficient using the TXpFilterBase.XSLProcessorFormatObject method.

TXpFilterBase.XslProcessorFormatObjectStart, p. 270

This event has been renamed to TXpFilterBase.XSLProcessorFormatObject and is declared as follows:

XSLProcessorFormatObjectStart virtual method

    procedure XslProcessorFormatObjectStart
      (Sender : TObject; aFormatObject : TXpFormattingObject); virtual;

=> Defines an event handler that is called when a formatting object is passed to the filter.

This is the event handler for the XSL processor's OnFormatObject event. When the XSL processor encounters a formatting object, it transfers the object to the filter via this method. Sender is the XSL processor raising the event. Parameter aFormatObject is the formatting object instance encountered by the XSL processor. When the formatting object's child elements have been processed, the XSL processor calls the XSLProcessorFormatObjectEnd method.

See also: XSLProcessorFormatObjectEnd

TXpFilterBase.XslProcessorResolveElement, p. 271

This method no longer exists.

TXpFilterBase.XslProcessorResolveElementCode, p. 272

This method no longer exists.

New method, XslProcessorTextNode:

XSLProcessorTextNode virtual method

    procedure XslProcessorTextNode(
      oOwner : TObject; oNode : TXpText); virtual;

=> Defines an event handler that is called when the XSL processor needs to copy the contents of a text node to the result tree.

This is the event handler for the XSL processor's OnTextNode event. See the XSL processor's OnText event reference to see when this event is raised. Parameter oOwner is the XSL processor raising the event. Parameter oNode is the text node whose contents are to be copied to the tree.

See also: XSLProcessorText

Top

### TXpFilterHTML Changes

OutputMode, p. 276

The default value is XphomFragment instead of XphomFull.

Top

### TXpFilterText Component

Use the text filter to create text-only documents. For example, the Text filter may be used to generate the contents of an email.

TXpFilterText.StringValue property

property StringValue : DOMString

=> Returns a concatentation of the text nodes within the result tree.

This method returns the concatenation of all text nodes within the result tree. Use this method if the text nodes in the result tree are formatted as necessary by the stylesheet. If the text nodes need to be separated by space characters, use the Text property instead.

See also: Text

TXpFilterText.Text property

property Text : DOMString

=> Returns a concatentation of the text nodes within the result tree with each text node separated by a space character.

This method returns the concatenation of all text nodes within the result tree, with each text node being separated by a space character. If the stylesheet generates text nodes that do not need to be separated by space characters, use the StringValue property instead.

See also: Text

Top

### TXpFilterXML Changes

The TXpFilterXML component is a descendant of the TXpFilterText component, inheriting its properties, methods, and events.

BodyOnly, p. 284

This property no longer exists.

New property DocTypePublic:

TXpFilterXML.DocTypePublic property

property DocTypePublic : DOMString

=> Specifies the public ID of the DTD in the output document.

The value for this property is ignored unless a value is also assigned to the DocTypeSystem property. If a value is specified for both properties, the value of this property is used as the public ID in the document type declaration in the output document.

See also: DocTypeSystem

New property DocTypeSystem:

TXpFilterXML.DocTypeSystem property

property DocTypeSystem : DOMString

=> Causes the XML filter to write a document type declaration to the output document.

If a value is assigned to this property, the XML filter writes a document type declaration to the output document. The value of this property is used as the system ID.

See also: DocTypePublic

New property OmitStandalone:

TXpFilterXML.OmitStandalone property

property OmitStandalone : Boolean

Default: True

=> Indicates whether the standalone attribute should be omitted from the XML declaration.

To have the XML filter write a standalone attribute to the output document, set this property to True. The value of the standalone attribute is determined by the value of the XML filter's Standalone property.

See also: OmitXMLDeclaration, Standalone

New property OmitXMLDeclaration:

TXpFilterXML.OmitXMLDeclaration property

property OmitXMLDeclaration : Boolean

Default: False

=> Indicates whether the XML declaration should be omitted from the document.

To have the XML filter write the XML declaration to the output document, assign the value True to this property.

See also: OmitStandalone, Standalone

New property Standalone:

TXpFilterXML.Standalone property

property Standalone : Boolean

Default: False

=> Controls the value output for the standalone attribute.

If the value of the OmitStandalone property is True, the value of this property controls the value of the standalone attribute written to the XML declaration. If the Standalone property has the value True then "standalone='yes'" is written to the XML declaration. Otherwise "standalone='no'" is written.

See also: OmitStandalone, OmitXMLDeclaration

Top

### TXpNode Changes

New property BaseURI:

TXpNode.BaseURIs read-only property

property BaseURI : DOMString

=> Returns the URI of the document containing the node.

Use this method to retrieve the absolute URI of the XML document containing the node. For example, if the TXpObjModel component loads the document N:\Images\Summary.xml then the base URI of the node is N:\Images\. The returned URI always includes a trailing path delimiter. Nodes in an external DTD always return the base URI of their parent DTD, not the document referencing the DTD.

TXpNode.ForceOwnerDocument, p. 112

The manual states "The current node must be of type TXpDocument". That statement is incorrect. The current node must be a descendant of class TXpNode. The example should be as follows:

    procedure CopyNodeToDOM(
      sourceNode : TXpNode; targetDocument : TXpDocument);
    begin
      aNode := sourceNode.CloneNode(True);
      targetDocument.ForceOwnerDocument(aNode);
    end;

New method LastDescendantOrSelf:

TXpNode.LastDescendantOrSelf read-only property

property LastDescendantOrSelf : TXpNode
=> Returns the last descendant of the node or the node itself if the node has no descendants.

Use this method to retrieve the last descendant node of the current node. For example, if node A has two child nodes with the second child node having child nodes B, C, and D then this method would return node D.

New method NextInDocument:

TXpNode.NextInDocument read-only property

property NextInDocument : TXpNode
=> Returns the next node in document order.
Use this method to retrieve the next node within the document. The next node is considered to be the node whose start tag is next encountered within the document. Algorithmically, this method retrieves the first child of the node. If none is found then it retrieves the next sibling of the node. If the node does not have a sibling then this method searches for an ancestor that has a sibling, returning the sibling. If this node is the last node in the document then this method returns nil.

See also: LoadDataSource, LoadMemory, RaiseErrors

New method PreviousInDocument:

TXpNode.PreviousInDocument read-only property

property PreviousInDocument : TXpNode

=> Returns the previous node in document order.

Use this method to retrieve the previous node within the document. The previous node is considered to be the node whose end tag occurs just prior to the start tag of this node. Algorithmically, this method finds the previous sibling of the current node. If none is found then it returns the parent of the current node or nil if the current node is the document root. If there is a previous sibling then this method returns the last descendant of the previous node or the previous node itself if the previous node has no descendants.

See also: LoadDataSource, LoadMemory, RaiseErrors

New method ResolveNSPrefix:

TXpNode.ResolveNSPrefix method

function ResolveNSPrefix(const sPrefix : DOMString) : DOMString;

=> Returns the namespace URI for the specified prefix.

Use this method to find the namespace URI for a namespace prefix. Starting with the current node, this method searches the node and its ancestors for a namespace declaration bearing the specified prefix. If the namespace declaration is found, this method returns the namespace URI otherwise it returns an empty string.

Top

### TXpNodeList Changes

New method Last:

TXpNodeList.Last read-only property

function Last : TXpNode

=> Returns the last node in the node list.

Use this method to retrieve the last node in the node list. If the node list does not contain any nodes then this method returns nil.

Top

### TXpObjModel Changes

OnSystemProperty, p. 97

This property is now of type TXpSystemLookupEvent.

    TXpSystemLookupEvent = procedure(oOwner    : TObject;
      sVarName  : DOMString; var sVarValue : DOMString) of object;

OnVariableLookup, p. 97

The TXpVariableLookupEvent now returns an instance of TXpValue. The TXpObjModel component is responsible for freeing the instance of TXpValue.

    TXpVariableLookupEvent = procedure(oOwner    : TObject;
      sVarName  : DOMString; var oVarValue : TXpValue) of object

New property DocLocation:

TXpParser.DocLocation read-only property

property DocLocation : string

=> Returns the location of the current document.

Use this property to determine the location of the document currently being parsed. For example, if the document is located on an ftp site then the returned value includes the ftp server name and directory (e.g., ftp://ftp.turbopower.com/pub/xpartner/demos). Note that the value of this property changes to reflect the document currently being parsed. If an XML document references an external DTD then the value of this property will reflect the location of the DTD while the DTD is being parsed. If this property returns an empty string then the parser is currently evaluating an internal entity or was passed a document located in a memory buffer or stream.

See also: DocName

New property DocName:

TXpParser.DocName read-only property

property DocName : string

=> Returns the name of the current document.

Use this property to determine the name of the document currently being parsed (e.g., products.xml, products.dtd). Use the DocLocation property to determine the document's location. Note that the value of this property changes to reflect the document currently being parsed. If an XML document references an external DTD then the value of this property will return the name of the DTD while the DTD is being parsed. If this property returns an empty string then the parser is currently evaluating an internal entity or was passed a document located in a memory buffer or stream.

See also: DocLocation

New property InCharSet:

InCharSet read-only property

property InCharSet: TXpCharEncoding

TXpCharEncoding = (ceUnknown, ceUTF8, ceUTF16LE, ceUTF16BE);

=> Indicates the current format of the document last read by the object model.

Use this property to determine the current format of the document just parsed by the object model.

See also: OutCharSet

New method LoadStream:

The object model can now load a document from a stream.

TXpObjModel.LoadStream method

function LoadStream(oStream : TStream) : Boolean;

=> Loads an XML document from a stream.

Use this method to load an XML document contained within a memory stream, file stream, or similar. Parameter oStream is the stream containing the XML document. This method begins reading from the stream's current position, returning True if the document is successfully loaded or False if a failure occurs.

See also: LoadDataSource, LoadMemory, RaiseErrors

New event OnCurrentNode:

TXpObjModel.OnCurrentNode event

property OnCurrentNode : TXpCurrentNodeEvent

    TXpCurrentNodeEvent = procedure(oOwner : TObject;
      var oCurrentNode : TXpNode) of object;

=> Called when the XPath engine needs to evaluate the current() function.

When the XPath engine encounters the XSLT current() function, it calls the handler assigned to this event. Parameter oOwner is the instance of TXpNode upon which the current XPath expression is being evaluated. The handler assigned to this event must place the current node into parameter oCurrentNode.

New event OnFormatNumber:

TXpObjModel.OnFormatNumber event

property OnFormatNumber : TXpFormatNumberEvent

    TXpFormatNumberEvent = procedure(oOwner : TXpNode;
      const sNumber, sPattern, sFormat : DOMString;
      var sFormattedNumber : DOMString) of object;

=> Called when the XPath engine needs to evaluate the format-number() function.

When the XPath engine encounters the XSLT format-number() function, it calls the handler assigned to this event. Parameter oOwner is the instance of TXpNode upon which the XPath expression is being evaluated. Parameter sNumber contains the value of the first parameter specified in the format-number() function. Parameter sPattern contains the value of the second parameter specified in the format-number() function. Parameter sFormat contains the value of the third parameter specified in the format-number() function. Since the third parameter is optional, parameter sFormat will contain an empty string if a third parameter was not specified. The handler for this event must place the formatted number in parameter sFormattedNumber.

New event OnKeyLookup:

TXpObjModel.OnKeyLookup event

property OnKeyLookup : TXpKeyLookupEvent

    TXpKeyLookupEvent = procedure(oDoc : TXpDocument;
      const sKeyName, sKeyValue : DOMString;
      oList : TXpNodeList) of object;

=> Called when the XPath engine needs to evaluate the key() function.

When the XPath engine encounters the XSLT key() function, it calls the handler assigned to this event. Parameter oDoc is the instance of TXpDocument containing the instance of TXpNode upon which the XPath expression is being executed. Parameter sKeyName is the value of the first parameter specified in the key() function. Parameter sKeyValue is the value of the second parameter specified in the key() function. Parameter oList is an instance of TXpNodeList that is empty. The handler assigned to this event must place the instances of TXpNode matching the key value into parameter oList. If no nodes match the key value then it should do nothing with parameter oList.

New event OnResolveDocument:

TXpObjModel.OnResolveDocument event

property OnResolveDocument : TXpResolveDocument Event

    TXpResolveDocumentEvent = procedure(oNode : TXpNode;
      const sHref, sBaseURI : DOMString;
      var oRoot : TXpDocument) of object;

=> Called when the XPath engine needs to evaluate the document() function.

When the XPath engine encounters the XSLT document() function, it calls the handler assigned to this event. Parameter oNode is the instance of TXpNode upon which the current XPath expression is being evaluated. Parameter sHref is the URI reference for the document to be loaded. It may contain either a relative or absolute reference (e.g., '../pub/talent.xml', 'c:\goals\verify.xml'). If the value of parameter sHref is an empty string (i.e., '') then the document being referenced is the stylesheet itself.

If the value of parameter sHref is a relative reference then parameter sBaseURI contains the base URI to use in resolving the relative reference. If the value of parameter sBaseURI is an empty string then the base URI of the current stylesheet node must be used to resolve the relative reference in parameter sHref.

After identifying the document to be referenced, the handler assigned to this event must load the document into an instance of TXpObjModel and return its document root in parameter oRoot.

New property OutCharSet:

OutCharSet property

property OutCharSet : TXpCharEncoding

TXpCharEncoding = (ceUnknown, ceUTF8, ceUTF16LE, ceUTF16BE);

=> Controls the output format of a document when saved using the SaveToFile method.

When an existing document is loaded, the value of this property defaults to the document's current format. To change the format in which an existing document is saved or to specify the format of a new XML document, set the value of this property to the desired format. The value ceUnknown is not considered to be a valid value for this property.

See also: InCharSet, SaveToFile

New method SaveToStream:

The object model can now save an XML document to a stream.

TXpObjModel.SaveToStream method

function SaveToStream(oStream : TStream) : Boolean;

=> Saves the XML document contained within the object model to a stream.

Use this method to save the object model's XML document to a memory stream, file stream, or similar. Parameter oStream is the stream to which the document is written. This method begins writing at the stream's current position, returning True if the document is successfully saved and False if it is not.

See also: SaveToFile

Top

### TXpParser Changes

New property DocLocation:

TXpParser.DocLocation read-only property

property DocLocation : string

=> Returns the location of the current document.

Use this property to determine the location of the document currently being parsed. For example, if the document is located on an ftp site then the returned value includes the ftp server name and directory (e.g., ftp://ftp.turbopower.com/pub/xpartner/demos). Note that the value of this property changes to reflect the document currently being parsed. If an XML document references an external DTD then the value of this property will reflect the location of the DTD while the DTD is being parsed. If this property returns an empty string then the parser is currently evaluating an internal entity or was passed a document located in a memory buffer or stream.

See also: DocName

New property DocName:

TXpParser.DocName read-only property

property DocName : string

=> Returns the name of the current document.

Use this property to determine the name of the document currently being parsed (e.g., products.xml, products.dtd). Use the DocLocation property to determine the document's location. Note that the value of this property changes to reflect the document currently being parsed. If an XML document references an external DTD then the value of this property will return the name of the DTD while the DTD is being parsed. If this property returns an empty string then the parser is currently evaluating an internal entity or was passed a document located in a memory buffer or stream.

See also: DocLocation

New method ParseStream:

The XML parser can now parse the contents of a stream.

TXpParser.ParseStream method

function ParseStream(oStream : TStream) : Boolean;

=> Parses the contents of a stream.

Use this method to parse an XML document from a stream. Parameter oStream is the stream containing the XML document. This method begins reading from the stream's current position, returning True if the document is successfully parsed or False if a failure occurs.

See also: ParseDataSource, ParseMemory, RaiseErrors

Top

### TXpText Changes

New function IsWhitespaceNode:

TXpText.IsWhiteSpaceNode method

function IsWhitespaceNode : Boolean

=> Returns True if the text node contains whitespace characters only.

Use this method to determine if the text node contains only whitespace characters. Whitespace is defined as a contiguous sequence of the characters #9 (tab), #10 (linefeed), #13 (carriage return), and #20 (space). Whitespace-only nodes contain only those characters defined as whitespace characters. If a text node contains any other character then it is not considered a whitespace node.

See also: TXpElement.StripWhitespaceNodes

New property OutputEscaping:

TXpText.OutputEscaping property

property OutputEscaping : Boolean

Default: True

=> Controls escaping of text nodes when being written to a file, stream, or memory.

When this property's value is set to True, characters within text nodes are written in their escaped form. For example, the character '<' is written as the string "<".

Top

### TXpValue Class (new)

This class, located in unit XPDOM, represents a value that can have one of four data types: Boolean, NodeSet, Number, or String.

TXpValue.Clone method

function Clone : TXpValue;

=> Makes a copy of the current instance.

Use this method to clone an instance of TXpValue.

TXpValue.AsBoolean property

property AsBoolean : Boolean

=> Retrieves or sets the value as a boolean.

Use this property to assign a Boolean value to the TXpValue instance or retrieve the value as a boolean regardless of its actual data type. The following table identifies how a non-boolean value is converted to a Boolean value:

Actual type | Conversion to Boolean
boolean | Left as is.
nodeset | Converted to True if the nodeset contains one or more nodes.
number | Converted to True if the number is not equal to zero.
string | Converted to True if the string contains at least one character.

See also: AsNodeSet, AsNumber, AsString, ValueType

TXpValue.AsNodeSet property

property AsNodeSet : TXpNodeList

=> Retrieves or sets the value as a nodeset.

Use this property to assign a nodeset to the TXpValue instance or retrieve the value as a nodeset. When reading this property, if the value's actual type is something other than a nodeset then this property returns nil.

See also: AsBoolean, AsNumber, AsString, ValueType

TXpValue.AsNumber property

property AsNumber : Double

=> Retrieves or sets the value as a number.

Use this property to assign a value of type Double to the TXpValue instance or retrieve the value as a Double regardless of its actual data type. The following table identifies how a non-numeric value is converted to a numeric value:

Actual type | Conversion to Double
boolean | Converted to one if the value is True otherwise converted to zero.
nodeset | The nodeset is converted to a string which is then converted into a number. If the string cannot be converted into a valid number then this property raises an error.
number | Left as is.
string | Converted to a number. If the string cannot be converted to a valid number then an exception is raised.

See also: AsBoolean, AsNodeSet, AsString, ValueType

TXpValue.AsString property

property AsString : DOMString

=> Retrieves or sets the value as a string.

Use this property to assign a string to the TXpValue instance or retrieve the value as a string regardless of its actual data type. The following table identifies how a value is converted to a string:

Actual type | Conversion to String
boolean | Converted to 'true' if True or 'false' if False.
nodeset | If the nodeset contains attribute nodes then the string a whitespace-separated list of the attribute values. If the nodeset contains any other kind of node then the string is a white-space separated list of the node text values.
number | Converted to a string using the FloatToStr function.
string | Left as is.

See also: AsBoolean, AsNodeSet, AsNumber, ValueType

TXpValue.SelectValue method

procedure SelectValue(
const sExpr : DOMString; oNode : TXpElement; oContextTXpNodeList);

=> Generates a value using an XPath expression.

Use this method to retrieve the value of an XPath expression. Parameter sExpr is the XPath expression. The expression is evaluated starting from the TXpElement instance specified by parameter oNode. Use the oContext parameter to specify the current nodeset for the expression. Once the expression is executed, determine the type of value generated by the expression using the ValueType property.

See also: ValueType

TXpValue.ValueType read-only property

property ValueType : TXpExpressionType

TXpExpressionType = (
xpetUnknown, xpetNodeSet, xpetBoolean, xpetNumber, xpetString);

=> Identifies the actual data type assigned to the instance.

Use this property to determine the data type assigned to the instance. This property is set when a value is assigned via the AsBoolean, AsNodeSet, AsNumber, AsString, and SetValue methods. This method returns one of the following enumerated values:

Value | Meaning
xpetUnknown | A value has not been assigned.
xpetNodeSet | The value is an instance of TXpNodeList containing zero or more instances of TXpNode.
xpetBoolean | The value is of type Boolean.
xpetNumber | The value is of type Double.
xpetString | The value is of type String.

See also: AsBoolean, AsNodeSet, AsNumber, AsString, SelectValue

Top

### Known Limitations

When saving an existing XML file, the Document Object Model (DOM) writes expanded entity references. The parser does not process an entity reference that precedes the declaration of the entity. The XPath ceiling and floor functions do not support NaN, positive zero, negative zero, positive infinity, and negative infinity.

The Print and RTF filters are not available in the Kylix version of XMLPartner Professional.
Top

### TXpXSLProcessor Changes

New support for global parameters

Values for global parameters declared via xsl:param elements within a stylesheet may be specified using the TXpXSLProcessor.SetParameter method. Global parameter values may also be read and cleared using the GetParameter and ClearParameters methods. Values for Parameters and variables are now specified using an instance of the TXpValue class.

TXpXSLProcessor.ClearParameters method

procedure ClearParameters;

=> Clears the value of all global parameters specified via the SetParameter method.

Use this method to clear the value of all global parameters declared via top-level xsl:param elements. If a global parameter does not have an explicit value then its default value takes effect the next time the parameter is referenced. Global parameters may not be cleared while a stylesheet is being applied to an XML document.

See also: GetParameter, SetParameter

TXpXSLProcessor.ClearVariables, p. 250

Global variables may not be cleared while a stylesheet is being applied to an XML document.

TXpXSLProcessor.GetParameter method

function GetParameter(const sName : DOMString) : TXpValue;

=> Retrieves the value of a global parameter.

Use this method to retrieve the value of a global parameter (i.e., a top-level xsl:param element in the stylesheet). Parameter sName is the name of the global parameter. If a value was not assigned to the parameter via the SetParameter method then this method returns nil. Otherwise, this method returns an instance of TXpValue. The value may be retrieved before or during the application of a stylesheet to an XML document. If retrieved during the application of a stylesheet then this method will return the default value of the parameter if no value was assigned via the SetParameter method. If this method returns nil then the global parameter does not exist in the stylesheet.

Note: If a filter component is being used, it is unlikely an application will be able to use this method during the execution of a stylesheet. This is because the XSL processor's event handlers are used by the filter component.

Important: The XSL processor is responsible for freeing the instance of TXpValue returned by this method.

See also: ClearParameters, SetParameter

TXpXSLProcessor.GetVariable, p. 252

This interface definition for this method has changed in order to support dynamic typing.

TXpXSLProcessor.GetVariable method

function GetParameter(const sName : DOMString) : TXpValue;

=> Retrieves the value of a global variable.

Use this method to retrieve the value of a global variable (i.e., a top- level xsl:variable element in the stylesheet). Parameter sName is the name of the global variable. The value returned depends upon the whether the stylesheet is executing and whether a value was assigned via the SetVariable method.

If the stylesheet is not executing and no value was assigned via the SetVariable method then nil is returned. In this situation, the XSL processor will not return the value of the variable as defined in the stylesheet.

If the stylesheet is not executing and a value was assigned via the SetVariable method then the stylesheet returns that value.

If the stylesheet is executing then this method will return the current value of the variable regardless of whether a value was assigned via the SetVariable method. If this method returns nil in this situation then the variable is not declared in the stylesheet.

Note that it is possible to retrieve the value of local variables if this method is used while the stylesheet is executing.

Note: If a filter component is being used, it is unlikely an application will be able to use this method during the execution of a stylesheet. This is because the XSL processor's event handlers are used by the filter component.

Important: In all cases, the XSL processor is responsible for freeing the instance of TXpValue returned by this method.

See also: ClearVariables, SetVariable

TXpXSLProcessor.SetParameter method

procedure SetParameter (const sName : DOMString; oValue : TXpValue);

=> Sets the value of a global parameter.

Use this method to set the value of a global parameter (i.e., a top- level xsl:param element in the stylesheet). Parameter sName is the name of the global parameter. Parameter oValue is an instance of TXpValue defining the value for the global parameter.

Important: The XSL processor is responsible for freeing the instance of TXpValue referenced by parameter oValue.

The value may be set before or during the application of a stylesheet to an XML document. If the global parameter is set during the application of a stylesheet then the value immediately takes effect.

Note: If a filter component is being used, it is unlikely an application will be able to use this method during the execution of a stylesheet. This is because the XSL processor's event handlers are used by the filter component.

See also: ClearParameters, GetParameter

TXpXSLProcessor.SetVariable method

procedure SetVariable (const sName : DOMString; oValue : TXpValue);

=> Changes the value of a global variable.

Use this method to change the value of a global variable (i.e., a top- level xsl:variable element in the stylesheet). Parameter sName is the name of the global variable. Parameter oValue is an instance of TXpValue defining the value for the global variable.

Important: The XSL processor is responsible for freeing the instance of TXpValue referenced by parameter oValue.

The value may be set before or during the application of a stylesheet to an XML document. If the global variable is set during the application of a stylesheet then the value immediately takes effect.

Note: If a filter component is being used, it is unlikely an application will be able to use this method during the execution of a stylesheet. This is because the XSL processor's event handlers are used by the filter component.

See also: ClearVariables, GetVariable

Embedding a stylesheet, p. 224

If an XML document contains a processing instruction, the XSL processor attempts to read the stylesheet specified by the processing instruction's href attribute. The href attribute may specify an embedded stylesheet using the value '#' concatenated with the value of xml:stylesheet's ID attribute. Alternatively, the href attribute may specify a stylesheet located on the local hard drive, a network hard drive, a web site (e.g., http://www.mydomain.com/styles/master.xsl), or an ftp site (e.g., ftp://ftp.mydomain.com/styles/master.xsl).

If the XML document contains more than one processing instruction then the XSL processor calls the event handler associated with the OnChooseStylesheet event. The application may use this event to tell the XSL processor which stylesheet is to be used.

TXpXSLProcessor.OnChooseStylesheet event

property OnChooseStylesheet : TXpChooseStyleEvent

    TXpChooseStyleEvent = procedure(oOwner : TObject;
      oStylePIs : TXpNodeList;
      var oChosenStyleIndex : Integer) of object;

=> Defines an event handler that is called when an XML document contains more than one processing instruction.

When processing an XML document containing two or more processing instructions (PIs), an application may use this event handler to decide which stylesheet to use. oOwner is the XSL processor calling the event handler. oStylePIs is a list containing two or more instances of TXpProcessingInstruction, one per PI. The Data property of each instance contains the attribute-like information associated with the PI (e.g., "alternate='yes' href='mystyle.xsl' title='Medium'"). Once the application has decided which TXpProcessingInstruction instance to use, place the index (zero- based) of the instance into the parameter oChosenStyleIndex. For example, setting parameter oChosenStyleIndex to the value one causes the XSL processor to use the second TXpProcessingInstruction instance.

For a description of the processing instruction, see the specification Associating Style Sheets with XML Documents Version 1.0, available at http://www.w3.org/TR/xml-stylesheet.

TXpXSLProcessor.OnFOProperty, p. 255

This event no longer exists. The transfer of formatting objects to a filter has been made more efficient using the TXpXSLProcessor.OnFormatObject event.

New event, TXpXSLProcessor.OnResolveConflict

TXpXSLProcessor.OnResolveConflict event

property OnChooseStylesheet : TXpChooseStyleEvent

    TXpResolveConflictEvent = procedure(oOwner : TObject;
      oNode : TXpNode; eEventCode : TXpConflictType;
      var bRaiseError : Boolean) of object;

    TXpConflictType = (xpctTemplateMatch, xpctCommentNodes,
      xpctPINodes);

=> Defines an event handler that is called when an XSL processor encounters a conflict.

In certain situations, the XSLT specification gives the XSL processor leeway to resolve a conflict by either raising an error or taking a corrective action. In some of those situations, the XMLPartner XSL processor raises this event so that the application may decide how to handle the situation.

The oOwner parameter is the XSL processor raising the event. The oNode parameter is the stylesheet node being executed at the time the conflict is detected. The eEventCode parameter describes the error as shown in the following table:

Event code | Meaning
xpctTemplateMatch | When searching for templates that match a particular node, the XSL processor found more than one template matching the node with each template having the same import precedence & priority. If the bRaiseError parameter is set to False, the XSL processor uses the last template declared in the stylesheet.
xpctCommentNodes | Instantiating the content of an xsl:comment element created nodes other than text nodes. If the bRaiseError parameter is set to False, the XSL processor ignores the xsl:comment element.
xpctPINodes | Instantiating the content of an xsl:processing- instruction element created nodes other than text nodes. If the bRaiseError parameter is set to False, the XSL processor ignores the xsl:processing-instruction element.

To have the XSL processor handle the situation by raising an exception, set the bRaiseError parameter to True. To have the XSL processor work around the problem, set the bRaiseError parameter to False. The previous table describes the work around for each type of conflict.

TXpXSLProcessor.OnResolveElement, p. 258

This event no longer exists.

TXpXSLProcessor.OnResolveElementCode, p. 258

This event no longer exists.

New event OnTextNode:

TXpXSLProcessor.OnTextNode event

property OnTextNode : TXpTextNodeEvent

    TXpTextNodeEvent = procedure(oOwner : TObject;
      oNode : TXpText) of object;

=> Defines an event handler that is called when an XSL processor needs to copy the contents of a text node to the result tree.

As described in the OnText event, the XSL processor copies text to the result tree when certain XSLT elements are executed. It may copy text by sending the text or by sending a text node to the filter. Parameter oOwner is the XSL processor raising the event. Parameter oNode is an instance of class TXpText whose contents are to be copied to the result tree.

New property OverrideFilter:

TXpXSLProcessor.OverrideFilter property

property OverrideFilter : Boolean

=> Forces the XSL processor to obey xsl:output elements in the stylesheet.

By default, the static filter referenced by an XSL processor's Filter property always takes precedence over the xsl:output element within a stylesheet. To have the XSL processor execute the xsl:output elements, set the Filter property to nil or set this property to True.

When this property is set to True, the XSL processor creates a dynamic filter according to the attribute values specified for the xsl:output element within the stylesheet. The dynamic filter is accessible via the Filter property until the XSL processor component is destroyed or a new value is assigned to the StyleData or StyleURL properties . After calling the ApplyStyle method, your code must tell the dynamic filter to save the result tree as shown in the following example:

    XSLProcessor.OverrideFilter := True;
    if XSLProcessor.ApplyStyle then
      XSLProcessor.Filter.SaveToStream(aMemStream);

See also: Filter

TXpXSLProcessor.StyleData, p. 260

Since this property is of type DOMString, the XSL processor must treat the data as though it is in UTF-8 or UTF-16 format. If the data does not have a byte order mark indicating it is UTF-8 or UTF-16, this property prefixes the data with a UTF-8 byte order mark.

TXpXSLProcessor.XpObjModel, p. 261

This property has been renamed to XmlObjModel. The manual states "Unless using an XML document that contains embedded XSL, ... If using embedded XSL, assign the document containing the XML and XSL data using the StyleData or StyleURL property." This is no longer true. An XML document containing an embedded stylesheet should be assigned to the XSL processor using the XmlObjModel property. The StyleData and StyleURL properties are only for assigning external stylesheets to the XSL processor.

Top

### XSLT Element Changes

xsl:call-template, p. 304

The example for xsl:call-template is incorrect. The corrected example is as follows:

          ..............................

xsl:message, p. 322

The Terminate attribute is declared as Boolean, not DOMString as is implied by the manual.

    TXpXSLMessageEvent = procedure(Sender : TObject;
      const Msg : DOMString; var Terminate : Boolean) of object;

xsl:namespace-alias, p. 323

If a conflict is detected, this element raises an exception. It does not call the handler for the RaiseConflictError property (which doesn't exist) or the OnResolveConflict property.

xsl:number, p. 325

The xsl:number element does not support format attributes having values such as '7' and '3334'.

The grouping-separator and grouping-size attributes do not have default values. According to the XSLT specification, both attributes must be explicitly assigned a value in order for the XSL processor to use the attributes. If either attribute is missing, the XSL processor ignores the existing attribute.

xsl:output, p. 331

The XSL processor ignores xsl:output elements unless a) the OverrideFilter property of the TXpXSLProcessor component is set to True or b) the Filter property of the TXpXSLProcessor component does not reference a static filter. If either condition is true, the XSL processor creates a dynamic filter based upon the attributes assigned to the xsl:output elements found within the stylesheet, including imported and included stylesheets. The dynamic filter temporarily replaces the static filter referenced by the Filter property of the TXpXSLProcessor component. The dynamic filter is automatically freed when the TXpXSLProcessor component is freed or when a new value is assigned to the StyleURL or StyleData properties of the TXpXSLProcessor component.

If a method attribute is not specified for an xsl:output element then the XSL processor creates a dynamic XML filter by default. This does not conform to the rules in Section 16 of the XSLT specification that state the criteria for creating a HTML filter by default. The criteria are dependent upon the content of the result tree. Because the XSL processor must create the filter before the result tree has been created, it cannot determine whether the criteria have been met.

To use the Print or RTF filters via an xsl:output element, set the method attribute to the value "tps:print" or "tps:rtf" where the prefix tps evaluates to the namespace http://www.turbopower.com/xmlpartner. None of the other attributes listed in the specification for xsl:output are applicable to the Print and RTF filters. When using the xsl:output method to control the output format, you must call the filter's SaveToFile or SaveToStream method. Since the dynamic filter is accessible via the Filter property of the TXpXSLProcessor component, you can write code as shown in the following example:

    XSLProcessor.Filter.SaveToStream(aFileStream);

xsl:sort, p. 341

On p. 342, the meaning of the lang attribute states "The XSL processor ignores this attribute. Sorting is performed using the locale of the current user." The lang attribute is no longer ignored. The XSL processor looks for a descendant of TXpComparator registered to handle the value of the lang attribute and the data type as specified by the data-type attribute. If none is found then the default comparator is used.

The default text comparator sorts the characters in ASCII order. Characters in the range 192-255 (i.e., Codepage 1252 used by Windows) are compared using three stages. The first stage is a case-insensitive comparison with characters converted to their unaccented equivalents. The second stage is a case-insensitive comparison using the accented characters. The third stage is a case-sensitive comparison using accented characters. The number comparator sorts numbers as though they are doubles. Values that are NaN (Not a Number) are sorted first.

To create comparators for other locales and cultures, you must create classes that inherit from TXpComparator in unit XpSort. You must register the classes using the TXpComparator Register and Unregister class functions. The sLang parameter of the Register class function must exactly match the value of the lang attribute used in xsl:sort. See the end of unit XpSort for an example.

xsl:template, p. 347

In the section Handling template conflicts, the XSL processor calls the OnResolveConflict event handler, not the RaiseConflictError event handler.

xsl:variable, p. 353

A global variable may not be referenced before it is declared.

Top

### Online Resources

You can get additional information from these online sources:

World Wide Web

Check TurboPower's web site regularly. The TurboPower staff posts white papers, competitive analyses, answers to frequently asked questions, sample applications, updated software, and information about new and existing products. You may want to check these URLs in particular:

Main TurboPower Web site: www.turbopower.com

XMLPartner Professional product information: www.turbopower.com/products/XMLPartner

Product updates: www.turbopower.com/updates

Newsgroups

TurboPower sponsors a variety of newsgroups where users can freely exchange information about TurboPower development tools and their use. The address of the news server is news.turbopower.com. There is a newsgroup for each TurboPower product. We strongly recommend that you use dedicated newsreader software to access our newsgroups. TurboPower newsgroups are public so please do not post confidential information (such as your serial number, CD-ROM unlocking code, or credit card data) on the newsgroups. If you are posting a debug log, or detailed session parameters, remember to blank out information that you don't want others to see (such as passwords and user IDs).

If you do not care to use the newsgroups, you can send technical support inquiries to mailsupport@turbopower.com. Please be aware, however, that due to the large number of people reading the newsgroup messages, your question will be answered fastest by using the newsgroups.

Electronic newsletters

TurboPower encourages you to subscribe to the free XMLPartner Electronic Newsletter at www.turbopower.com/tpslive. Electronic newsletters keep you up-to-date on product developments via e-mail. You will receive automatic notification of new downloadable updates, upgrades, and special offers. There is an Electronic Newsletter for each TurboPower product. You can subscribe or un-subscribe at any time.

Top

Copyright 2001 TurboPower Software Company. All rights reserved.