4
The XML Cursor (doccursor)
The doccursor object is always a child of an XML Document. It refers to a node in the DOM tree, which is saved in the XML Document (the parent).
There are methods to set the reference to a different node of the DOM tree. In other words this means that the XML Cursor can be moved in the DOM tree through methods. It will remain a child of the XML Document of course.
Definition
{ export | reexport } { model } doccursor { <Identifier> }
{
[ <atribute definition> ]
[ <method definition> ]
}
Besides the normal
ISA Dialog Manager attributes, the XML Cursor attribute contains additional attributes which make it possible to access properties such as name, value or other attributes of the DOM nodes. Because these are runtime attributes, they cannot be passed down. In addition, many of these attributes can only be read because the corresponding properties of the DOM nodes cannot be changed.
The XML Cursor is initially invalid, but as soon as it is accessed for the first time it will be automatically positioned to the root of the DOM tree. Note that this also happens when the XML Cursor gets invalid through an action. The attribute .mapped shows if the XML Cursor is valid or not.
Events
None
Children
Parents
Menu
None
Methods
4.1 Attributes
4.2 Object-specific Attributes
.attribute[integer]
attribute[string]
Depending on the indexing, the attribute “attribute” serves for querying the name or the value of a DOM nodes’ attributes .
If the index is a number, the name of the corresponding attribute of a DOM node will be delivered. Take note that attributes of DOM nodes usually are unsorted.
If the index is a string, then the index is regarded as a name of an attribute and the value of this attribute is returned. An assignment to an attribute indexed with a string creates a corresponding attribute for the DOM node. The assignment of an empty string deletes the corresponding attribute of the DOM node.
This attribute is not passed down because it refers to a runtime characteristic.
Is for setting and retrieving the data within a DOM node. The attribute is only available when the node type is either nodetype_cdata_section or nodetype_processing_instruction.
This attribute is not passed down because it refers to a runtime characteristic.
The IDispatch COM interface pointer of the XML Cursor can be accessed through the attribute idispatch under Microsoft Windows.
In the Rule Language the attribute can only be assigned to the same attribute of a different IDM object. Be aware, that in the programming interface the COM object is only valid during the time when it is in use by the ISA Dialog Manager. Therefore, an application should increase its reference counter (COM Method: IUnknown->AddRef). When the object is no longer needed, the counter should be decreased (COM Method: IUnknown->Release). Please note, the counter cannot be decreased more often than it is increased. Otherwise, the COM object will be released. The ISA Dialog Manager cannot recognize this situation and this will lead to a system crash.
This attribute is not passed down because it refers to a runtime characteristic.
The IXMLDOMNode COM interface pointer of the XML Cursor can be accessed through the ixmldomnode attribute under Microsoft Windows.
In the Rule Language the attribute can only be assigned to the same attribute of a different IDM object. Be aware, that in the programming interface the COM object is only valid while it is in use by the ISA Dialog Manager. Therefore, an application should increase its reference counter (COM Method: IUnknown->AddRef). When the object is no longer needed, the counter should be set back again, or decreased (COM Method: IUnknown->Release). Please note, the counter cannot be decreased more often than it is increased. Otherwise, the COM object will be released. The ISA Dialog Manager cannot recognize this situation and this will lead to a system crash.
This attribute is not passed down because it refers to a runtime characteristic.
The IXMLDOMNodeList COM interface pointer of the XML Cursor can be accessed through the ixmldomnodelist attribute under Microsoft Windows. The direct children of the XML Cursor can be accessed through the interface pointer.
In the Rule Language the attribute can only be assigned to the same attribute of a different IDM object. Be aware, that in the programming interface the COM object is only valid while it is in use by the ISA Dialog Manager. Therefore, an application should increase its reference counter (COM Method: IUnknown->AddRef).). When the object is no longer needed, the counter should be decreased (COM Method: IUnknown->Release). Please note, the counter cannot be decreased more often than it is increased. Otherwise, the COM object will be released. The ISA Dialog Manager cannot recognize this situation and this will lead to a system crash.
This attribute is not passed down because it refers to a runtime characteristic.
Is true when the XML Cursor points to a node in the DOM tree. Please take note that an XML Cursor, which does not reference any node in the DOM tree, is automatically positioned on the root of the DOM tree when any object-specific attribute is accessed or when an object-specific method is invoked.
This attribute is not passed down because it refers to a runtime characteristic.
Refers to the name or tag of the DOM node.
This attribute is not passed down because it refers to a runtime characteristic.
This serves for querying the type of DOM node.
This attribute is not passed down because it refers to a runtime characteristic.
Delivers a string representation for the position of the XML Cursor in the DOM tree. The select method can be called with this string in order to position an XML Cursor to the nodes in the DOM tree.
If the value of the path attribute is stored somewhere else (i.e. in the userdata attribute), then it is important to know that these stored values will not be adjusted when the structure of the DOM tree changes. When the select method is invoked with the stored value afterward, the XML Cursor will point to an incorrect DOM node.
This attribute is not passed down because it refers to a runtime characteristic.
Is the public identifier of the DOM node. The attribute is only available, when the node type is either nodetype_entity or nodetype_notation.
This attribute is not passed down because it refers to a runtime characteristic.
This reveals if an attribute of a DOM node was explicitly given, or if it was inherited from a standard value. The attribute is always true except for the node type nodetype_attribute.
This attribute is not passed down because it refers to a runtime characteristic.
Is the system identifier of DOM nodes. This attribute is only available when the node type is either nodetype_entity or nodetype_notation.
This attribute is not passed down because it refers to a runtime characteristic.
Is the name of the instruction for a DOM node. The value is the same as the value of the name attribute. This attribute is only available when the node type is nodetype_processing_instruction.
This attribute is not passed down because it refers to a runtime characteristic.
Is the value of all sub-nodes within a DOM node. A string is delivered which represents the text of all sub-nodes. This attribute is mainly helpful when only the text of an XML element is needed, as it is not required to navigate to the child nodes containing the actual text.
Please note that setting this attribute automatically deletes all child nodes and inserts a new text node.
This attribute is not passed down because it refers to a runtime characteristic.
Is the value of a DOM node. This attribute is only available when the node type is nodetype_attribute, nodetype_text, nodetype_cdata_section, nodetype_processing_instruction or nodetype_comment.
This attribute is not passed down because it refers to a runtime characteristic.
String representation of a DOM node and all of its child nodes.
This attribute is not passed down because it refers to a runtime characteristic.
4.3 Object-specific Methods
Inserts a child node as the last node to the current DOM node. The XML Cursor is then set to the new element.
Deletes the DOM node and all of its child nodes. The XML Cursor is then positioned to the father node. The XML Cursors, which point to the deleted DOM nodes in the sub-tree, become invalid. The attribute .mapped has the value false for invalid XML Cursors.
When the value of the path attributes is stored elsewhere (i.e. in userdata attribute), then it is important to know that these stored values will not be adjusted when the structure of the DOM tree changes. When the select method is invoked with the stored value afterward, the XML Cursor will point to an incorrect DOM node.
Tests if the DOM node satisfies the given pattern (see chapter “Pattern for the Methods :match() and :select()”).
Reallocates the DOM node with all of its child nodes.
When the value of the path attributes is stored elsewhere (i.e. in userdata attribute), then it is important to know that these stored values will not be adjusted when the structure of the DOM tree changes. When the select method is invoked with the stored value afterward, the XML Cursor will point to an incorrect DOM node.
Moves the XML Cursor in the given direction or moves the XML Cursor to the first DOM node that matches the given pattern (see chapter “Pattern for the Methods :match() and :select()”).
Transforms the XML Cursor with the given scheme. When the target is an XML Document, the saved DOM tree is deleted, and a new tree is built. All existing XML Cursors become invalid. The attribute .mapped has the value false for invalid XML Cursors.
Alternatively, the target can be a text or file. If the result of the transformation is no legal XML format, then it needs to be directly converted into a text or file, as the result cannot be assigned to an XML Document. This is true, for example, for conversions to HTML.
4.4 Pattern for the Methods :match() and :select()
A pattern is very similar to a ISA Dialog Manager identifier. The pattern represents a path of element names. The path starts at the root of the tree. Each hierarchical level is compared to the corresponding part of the path. Here it is possible to define certain characteristics of the father such as existence of an attribute or the position within the children.
Basically all characters except ., [, ", ], <, >, =, \, tab, space and line break can be used in the pattern. If one of the characters mentioned above, without the page break, shall be used, then it has to be escaped with a \ before the character. Between double quotes ("), that is within a string, the following symbols are also allowed: ., [, ], <, >, =, tab and line break. Please note that in the dialog script the symbol \ within a string already is an escape symbol. Due to this it is important to use \\ in a dialog script whenever a \ is needed. Also in a dialog script \" has to be used whenever the character " is needed.
<Name>
Is compared to the name attribute of the XML Cursor. The XML Cursor must possess the node type nodetype_element. Alternatively, the character * can be used. In this case the name attribute will not be taken into consideration.
The name of an XML element starts with a letter or an underline. It may contain letters, digits, hyphens, underlines and dots. The exact definition of an XML element name can be found in the XML specifications (www.w3c.org/XML).
<Attr>
The DOM node that points to the XML Cursor must possess the given attribute.
The name of an XML attribute starts with a letter or an underline. It may contain letters, digits, hyphens, underlines and dots. The exact definition of an XML attribute name can be found in the XML specifications (www.w3c.org/XML).
<Op>
Is a comparison operator which compares the attribute given in <Attr> with <Value>. It can be tested for equality = and inequality <>.
<Value>
Is the value to which the <Attr> is compared.
<Idx>
The DOM node must be at this position within the child nodes of the same parent. The first child has position 1.
<Idx> consists only of figures (0 – 9), which are interpreted as number.
Particularities
When the pattern start with a dot, it is relative to the current DOM node. This means that the path begins at the current DOM node.
Two consecutive dots define, that an arbitrary number of hierarchy levels may be skipped.
[<Idx>]
An index without any further information selects the DOM node at this position. In this case, the type of DOM node is insignificant. Thus each DOM node can be uniquely referenced by an expression like {[<Idx>][.[<Idx>]]} (path attribute).
Additions for Microsoft Windows
XPath can also be used as pattern syntax. Here, the pattern must start with either / or ./. The use of XPath patterns is not supported on all platforms and therefore not portable.
Support