Since JoPPS v 2.82 there is native support in the scripting language for manipulating, reading and writing XML files. The components presented here are part of the DOM way to traverse and query XML. Not all related XML standards are implemented here, but some are to help facilitate these kind of operations.
It needs to be noted that these components and classes are working on Strings only, and that no interpretation or immediate conversion is made. For import and export purposes, these interpretations and conversions are to be made by the writer of the script(s)!
However, conversion between strings you pass onto these functions and encoding (both read to string and write to file) of the file is automatic, including special XML encoding for special characters (i.e.: & = ‘&’).
The following chapters detail all of the XML related objects, their methods and properties. It needs to be noted that XMLNode is an object that cannot be instantiated, but that all of XMLAttribute, XMLElement, XMLCData and XMLText are all inheriting from XMLNode and are in fact all a XMLNode.
The XMLDocument class
An XMLDocument is a wrapper for all extra functionalities that are not related to nodes and elements. Loading and Saving of XML documents happens through this object, and the creation of new documents also.
You can also navigate your entire document from here.
Properties and Methods
This constructor creates a new XMLDocument, with a root element.
This means that you can call SaveFile() immediately after and that this call creates the following XML file.
This method clears the entire XMLDocument, as if you had created a new object.
LoadFile( fileName : string/URI): Boolean;
This function loads a XML file into memory. The result of this method indicates if the operation was successful or not.
If the operation fails, please consult Errors or HasErrors().
Note! If there is a reference to a DTD file inside the document, this DTD needs to be accessible by the parser or the result will inevitably always be false. The same can happen with badly formed or corrupt XML files or usage of another character set than specified in the encoding attribute of the XML file!
SaveFile( fileName : string/URI): Boolean;
This method writes the document to disc, in the UTF-8 encoding and with readable indentation.
The result indicates if the operation was successful or not.
This method returns true if an error occurred during the last operation on the XMLDocument. It would then also be possible to get an errormessage (in English) using the Errors property.
Property DocumentRoot : XMLElement (read-only)
This property returns the root node of the document if it exists, otherwise it returns 
Nil
. The only way this could happen is when you read in a file that is not a valid XML file and that doesn’t contain a root node. After creation, or directly after ClearDocument(), this returns the element for root /.
Property Errors : String (read-only)
This property returns an empty string when no error occurred up until now (XMLDocument.HasErrors() = false). It returns a message in English with respect to the first error that occurred during the last reading or writing operation on the XMLDocument when XMLDocument.HasErrors() = true is the case.
The XMLNode class
This object type is the ancestral type for XMLAttribute, XMLElement, XMLCData and XMLText. All methods and properties as explained here are also valid for those object types. They will not be repeated there unless something is different in behaviour or result.
Caution! Be careful with files that were read in. There are different kind of types of nodes. Use XMLNode.NodeType to determine what functionality is available.
Caution! The functionalities to navigate in XMLNodes are valid only in documents, not in XMLNodeLists.
XML_ELEMENT_NODE // = ELEMENT_NODE uit XML specificatie;
XML_ATTRIBUTE_NODE // = ATTRIBUTE_NODE uit XML specificatie;
XML_TEXT_NODE // = TEXT_NODE uit XML specificatie;
XML_CDATA_SECTION_NODE // = CDATA_SECTION_NODE uit XML specificatie;
These are constants that map directly to values that can be found in the XML DOM specification. For clarity they were fitted with a 'XML_' prefix to rule out possible double definitions.
This method on XMLNode cannot ever be called from script. It cannot be created, but it can be used. A Node can represent an XML Element, a piece of text, or a comment, or an attribute, or …. XMLNodes are queried into a XMLNodeList after a XPath query for instance.
Property NodeName : String;
NodeName is a read/write property that returns a String. Depending on the derivative objecttype represented by a XMLNode, this property returns and sets something different.
Please consult the derivative classes for more information.
Property NodeValue : String;
NodeName is a read/write property that returns a String. Depending on the derivative objecttype represented by a XMLNode, this property returns and sets something different.
Please consult the derivative classes for more information.
Property NodeType : Integer; (read-only)
NodeType is a read-only property that returns one of the constants in the above chapter. This way you can determine what subtype of XMLNode this instance is.
Property ParentNode : XMLNode; (read-only)
A XML Document is constructed as a tree structure. Every node – Element, Comment, Attribute or something else – has a parent node to which it is child node. The big exception is the root node of the tree structure (XMLDocument.DocumentRoot).
This property always returns a subtype of XMLNode (or at least a XMLNode) object terug. The returned value needn’t be freed later on in the script. In case of the root node, this property returns Nil.
Objects that were recently created and not attached to some other node (either explicitly or implicitly), are considered root nodes as well.
This method returns whether this node is a so called leaf node or that it is a parent node for other nodes as well. For instance a XMLElement with subelements or text!
GetFirstChild() : XMLNode;
This method returns the first child node or Nil if there is none.
Caution! When reading files, be careful. There exist multiple types of nodes, and for now there are only some converted to a valid object (XMLElement, XMLAttribute, XMLText en XMLCData). All other node types are returned as XMLNode objects. XMLAttribute objects however are NOT fetched this way.
GetLastChild() : XMLNode;
This method fetches the last of the dependent child nodes or Nil if there are none.
See the remark in GetFirstChild() for more info.
GetNextSibling() : XMLNode;
This method fetches the next childnode following the node on which you called this method in its parentNode or Nil if there are none.
See the remark in GetFirstChild() for more info.
GetPreviousSibling() : XMLNode;
This method fetches the previous childnode before the node on which you called this method in its parentNode or Nil if there are none.
See the remark in GetFirstChild() for more info.
GetNextInDocument() : XMLNode;
This method fetches the next node using a so called depth first algorithm. This means that the next XMLNode gives the same result as calling GetFirstChild() if HasChildren() is true. If there are no childnodes, then it returns the same as GetNextSibling(). If that is still Nil , it calls ParentNode.GetNextSibling(). It keeps on doing these steps until either ParentNode = Nil, in which case the result is also Nil , or a node is found.
See the remark in GetFirstChild() for more info.
GetPreviousInDocument() : XMLNode;
First fetches the deepest level using the last childnode of the previous sibling (if any). If no previous sibling is encountered, the parent node is returned. Returns Nil if the XMLNode on which this method is called is a root node.
See the remark in GetFirstChild() for more info.
XMLNodeLists are used throughout the DOM model to designate collections of XMLNode objects. Every time a method returns more than 1 XMLNode, this object type will be the return type. We do not offer the possibility to create this kind of object. Note however that unless specified differently in the methods explanations, the result of such methods that return XMLNodeList objects, should be freed manually to prevent memory leaks! All properties are read only!
Caution! The functionalities to navigate in XMLNodes are only valid in documents, not in XMLNodeLists.
Property NodesCount : Integer;
Returns the number of XMLNodes in this list. Using the indexed property Nodes[] will require an index in the range 0 = index NodesCount.
Property Nodes[ index : Integer ] : XMLNode;
Returns the element designated by index. An error will occur if index 0, or index = NodesCount. On an empty XMLNodeList every acces to this property will result in an error.
Property CurrentNode : XMLNode;
On creation, CurrentNode is made equal to the first XMLNode ( index = 0 ), if there is one. Calling this method can result in an error if the list is empty or one of the previous operation has put the internal pointer index to a value greater than or equal to NodesCount or to an index 0.
See remarks on GotoFirst(), GotoLast(), Next() and Previous() to see where the internal pointer index is placed. This is an implicit call to Nodes[].
Places the internal pointer index for CurrentNode to the first index. A next call to CurrentNode is the same as a call to Nodes[ 0 ].
Places the internal pointer index for CurrentNode to the last index. A next call to CurrentNode is the same as a call to Nodes[ ( NodesCount – 1 ) ].
To check if the internal pointer index is pointing to the first node (CurrentNode = 0 ). This is always the case with newly fetched XMLNodeLists.
To check if the internal pointer index is pointing to the last node (CurrentNode = NodeCount ).
IsValidCurrentNode() : Boolean;
Use this method to determine if a call to CurrentNode would return a valid node, or a bad index error.
Returns true if the XMLNodeList contains no XMLNodes.
First increments the internal pointer index and then returns CurrentNode. It can lead to errors in the script if CurrentNode was the last node in the nodelist before the call was made or if the list is empty.
First decrements the internal pointer index and then returns CurrentNode. It can lead to errors in the script if CurrentNode was the first node in the nodelist before the call was made or if the list is empty.
The XMLText class
An XMLText object is a derivative of XMLNode. This means that everything that applies to a XMLNode, also applies to XMLText
In the next piece of XML file, 'this is text' is a XMLText node when read from a file into an object tree.
anElementthis is text/anElement
…
With these kind of nodes, special XML characters are taken into account. For instance the ‘&’ character is replaced by ‘&’ when the XMLDocument on which this text node is attached is written to a file. Leading and trailing so called ‘whitespace‘ are trimmed. If you want a piece of preformatted text inside the file, that is exactly the same when you read it out of a file next time, you need to use XMLCData.
You cannot create XMLText objects through a XMLText.Create() statement. This kind of objects is created automatically when you get or set the Value or NodeValue properties of an XMLElement, or when you call XMLElement.AddText() or when you read in a XML files.
However, the method is callable due to the nature of the scripting module. When you try to call this constructor, an error is generated.
Property NodeName : String; (read-only)
Always returns an empty string for this type of XMLNode.
Property NodeValue : String;
Returns or sets the content of the text node (in the example above, ‘this is text’). It is converted into readable text, and not in the encoding that is employed in the XML file.
Property NodeType : Integer; (read-only)
The value for this kind of XMLNode is always XML_TEXT_NODE.
The XMLCData class
An XMLCData object is a derivative of XMLNode. This means that everything that applies to a XMLNode, also applies to XMLCData.
In the next piece of XML file, 'this is text' is a XMLCData node when read from a file into an object tree.
…
anElement![CDATA[ this is text & this too
…
With these kind of nodes, special XML characters are taken into account. For instance the ‘&’ character is replaced by ‘&’ when the XMLDocument on which this text node is attached is written to a file. Leading and trailing so called ‘whitespace‘ are trimmed. If you want a piece of preformatted text inside the file, that is exactly the same when you read it out of a file next time, you need to use XMLCData.
You cannot create XMLCData objects through a XMLCData.Create() statement. This kind of objects is created automatically when you get or set the Value or NodeValue properties of an XMLElement, or when you call XMLElement.AddCData() or when you read in a XML files for all blocks surrounded by !CDATA[…]].
However, the method is callable due to the nature of the scripting module. When you try to call this constructor, an error is generated.
Property NodeName : String; (read-only)
Always returns an empty string for this type of XMLNode.
Property NodeValue : String;
Returns or sets the content of the text node (in the example above, ‘ this is text & this too ’+CrLf). It is converted into readable text, and not in the encoding that is employed in the XML file.
Property NodeType : Integer; (read-only)
The value for this kind of XMLNode is always XML_CDATA_SECTION_NODE.
The XMLAttribute class
An XMLAttribute object is a derivative of XMLNode. This means that everything that applies to a XMLNode, also applies to XMLAttribute.
Properties and Methods
Creates an attribute object that is not attached to a document or an element. Either use XMLElement.CreateAttribute() to create an attribute on a specific XMLElement, or XMLElement.AddAttribute() with your attribute object - that you just created with this constructor - as argument.
Do not forget to at least set the (Node)Name property after a call to this constructor.
This clears the (Node)Value property.
Property NodeName : String; (read-only)
Returns the same value as returned by the Name property.
Property NodeValue : String;
Returns the same value as returned by the Value property.
Property NodeType : Integer; (read-only)
The value for this kind of XMLNode is always XML_ATTRIBUTE_NODE.
This property sets or gets the name of the XMLAttribute. E.g. in the next piece of XML file the attribute name is 'length'.
profile length="7000" /
…
If setting the name and the new value is an empty string, an error is generated at run-time.
This property sets or gets the value of the XMLAttribute. E.g. in the next piece of XML file the attribute value is '7000'.
…
profile length="7000" /
…
You can place an empty string in the value property.
The XMLElement class
An XMLElement object is a derivative of XMLNode. This means that everything that applies to a XMLNode, also applies to XMLElement.
Properties and Methods
Creates an element object that is not attached to a document or an element. Either use XMLElement.CreateElement() to create an element on a specific XMLElement, or XMLElement.AddElement() with your element object – that you just created with this constructor - as argument.
Do not forget to at least set the (Node)Name property after a call to this constructor.
This method clears all underlying attributes, text or elements.
AddAttribute( att : XMLAttribute );
AddAttribute( att : XMLAttribute; position : Integer = -1 );
This method adds a previously created attribute object to the current XMLElement.Attributes[] property on the position denoted by theposition argument. If position denotes an impossible position – position 0 or position = AttributeCount – then the attribute is attached as last attribute. When an attribute with this name already exists, an error occurs unless the att object is the same object as the one already attached. In that case, nothing happens and no error occurs..
When att is Nil or att.NodeName is empty, an error will occur.
AddElement( el : XMLElement );
AddElement( el : XMLElement; position : Integer = -1 );
This method adds a previously created element object to the current XMLElement.Elements[] property on the position denoted by theposition argument. If position denotes an impossible position – position 0 or position = ElementCount – then the element is attached as last element.
When el is Nil or att.NodeName is empty, an error will occur.
AddCData( sText : String );
Adds a piece of text as the last child of an XMLElement. A XMLCData Node is attached behind the scenes with as NodeValue the value of sText.
See XMLCData for more information.
AddText( sText : String );
Adds a piece of text as the last child of an XMLElement. A XMLText Node is attached behind the scenes with as NodeValue the value of sText.
See XMLText for more information.
CreateAttribute( attName : string ) : XMLAttribute;
CreateAttribute( attName : string; attValue : string = '' ) : XMLAttribute;
CreateAttribute( attName : string; position : Integer = -1 ) : XMLAttribute;
CreateAttribute(attName:string; attValue:string = ''; position:Integer = -1 ) : XMLAttribute;
This method creates on the current XMLElement object an attribute with as NameattName and as ValueattValue. It returns the newly created attribute after it was inserted at position. All other restrictions for position as described in AddAttribute are valid here as well as the same behaviour.
CreateElement( elName : string ) : XMLElement;
CreateElement( elName : string; elValue : string = '' ) : XMLElement;
CreateElement( elName : string; position : Integer = -1 ) : XMLElement;
CreateElement( elName : string; elValue : string = ''; position : Integer = -1 ) : XMLElement;
This method creates on the current XMLElement object an element with as NameelName and as ValueelValue. It returns the newly created XMLElement after it was inserted at position. All other restrictions for position as described in AddElement are valid here as well as the same behaviour.
Property AttributeCount : Integer; // (read-only)
This property returns how many attributes are attached to this XMLElement object. When using the Attributes[] property, remember that values for index should always be smaller than the returned value of AttributeCount, but = 0.
Property Attributes[ index : Integer] : XMLAttribute; // (read-only)
Property Attributes[ attName : String ] : XMLAttribute; // (read-only)
The way to navigate over attributes of a XMLElement object. The index argument should be between 0 (inclusive) and AttributeCount. When given an index out of that range, an error is generated. When using the attName variant, this property acts the same way as GetAttributeByName().
GetAttributeByName( attName : String ) : XMLAttribute;
Attempts to return an attribute with the name = attName on this element or Nil if none can be found. Remember that XML is case sensitive!
Property ElementCount : Integer; // (read-only)
This property returns how many elements are attached to this XMLElement object. When using the Elements[] property, remember that values for index should always be smaller than the returned value of ElementCount, but = 0.
Property Elements[ index : Integer] : XMLElement; // (read-only)
A way to navigte over the subelements of a XMLElement object. The index argument passed to this property must lie between 0 (inclusive) and ElementCount or an error is generated.
GetElements() : XMLNodeList;
Returns a list with all subnodes of a XMLElement that are of type XMLElement. This list only contains XMLNodes of the type XMLElement. Remember to free the XMLNodeList that is returned manually!
GetElementsByName( elName: String ) : XMLNodeList;
Returns a list with all subnodes of a XMLElement of the type XMLElement and – if elName is a valid name for a XMLElement node - with NodeName = elName. Comparisons are – as always with XML entities - case-sensitive. Remember to free the XMLNodeList that is returned manually!
QueryForNode( xPathQuery : String ) : XMLElement
This method can be called on any object anywhere in a XML DOM hierarchy (on every XMLElement node) and is a way to enhance and speed up queries in the entire document (when xPathQuery starts with '/') or from that XMLElement on in the document.
The syntax of the xPathQuery argument requires a whole document of its own and is beyond the scope of this documentation. XPath is a standardized way to query XML documents in a way that SQL is for a relational database.
The result is the first (or only) XMLNode object that fullfills the conditions of that query or Nil if there are none.
Navigation on that returned XMLNode (XMLElement) happens as if you used the other navigational methods to that XMLElement. It returns the XMLNode object in the context of the XMLDocument, and not in the context of a result of a query.
If you want to use the resultset to navigate over, better use the XMLElement.QueryForNodeList() variant.
For more and better documentation and explanations concerning the XPath functionality, see any advanced XML, XSLT course or tutorial or use the free online course on http://www.w3schools.com/XPath/ .
This function is equivalent with the standard XML DOM function SelectSingleNode();.
QueryForNodeList( xPathQuery: String ) : XMLNodeList
All explanations and arguments as in XMLElement.QueryForNode() remain. The only differences are that this method always returns a XMLNodeList (that needs to be freed manually) and that the result always contains 0 or more XMLNode objects.
See XMLElement.QueryForNode() for a better explanation.
This function is equivalent with the standard XML DOM function SelectNodes();.
Property NodeName : String; (read-only)
Returns the same value as returned by the Name property.
Property NodeValue : String;
Returns the same value as returned by the Value property.
Property NodeType : Integer; (read-only)
The value for this kind of XMLNode is always XML_ELEMENT_NODE.
This property sets or gets the name of the XMLElement. E.g. in the next piece of XML file the element name is 'profile'.
profile length="7000" /
…
When setting the name and the new value is an empty string, an error is generated at run-time.
This property sets or gets the value of the XMLElement. E.g. in the next piece of XML file the element value is ''.
…
profile length="7000" /
…
Important to remember is that we currently only support so called #PCDATA. This also entails that all contents are to be translated to the encoding character set of the document. See XMLText for more information. Currently for documents that are to be created, only “UTF-8” encoding is supported. For read in XML Documents in other encodings, no guarantees are made, but chances are that they can keep this encoding on the next save of the document (even when additions have been made).
You can place an empty string in the value property or call XMLElement.Clear() to clear the value. This also means that when setting the value of a XMLElement node this is what happens:
…
myElement.Clear();
myElement.AddText( someValue );
…