InsertElementBefore (XmlNode function)

Insert an Element before this node (XmlNode class)

[Requires Janus SOAP]

This callable function inserts an Element node as the sibling immediately preceding the method XmlNode. InsertElementBefore also lets you add a Text node as the child of the inserted Element, and it lets you specify the namespace URI for the inserted element.

Syntax

[%outNod =] nod:InsertElementBefore( name, [value], [uri])

Syntax terms

%outNod	If specified, an XmlNode that is set to point to the Element node that is inserted.
nod	XmlNode that points to the (non-Root) node before which the Element node is inserted.
name	A Unicode string that is the name of the inserted Element; if prefixed, the prefix must be declared, or a uri argument must be provided. The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 127 characters (100 characters prior to version 7.7 of Janus SOAP).
value	This optional argument is the content of a Text node that is added as a child of the inserted element. This Unicode string content is stored without any normalization, entity substitution, etc. Since Text nodes cannot contain the null string, this argument is ignored if it is the null string.
URI	This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See "Usage Notes," below.

Usage notes

• If a URI argument is specified, the XmlDoc's Namespace property must be On, and URI must either be the null string, or it must have the format of an absolute URI. The effect depends on whether the name value includes a prefix:
  • If name has a prefix, URI must not be the null string, and URI is the declared namespace URI associated with that prefix and added element.
  • If name does not have a prefix:
    • If URI is the null string, the added element does not have a default namespace. Any in-scope default namespace the added element might have inherited, is not inherited.
    • If URI is not the null string, the added element has URI as the default namespace.

  If a non-null string URI argument is provided, and the namespace declaration resulting from it is not in scope for the added element, then a namespace declaration is added at that element.

• If the URI argument is not present, the added element's namespace is determined by the prefix and in-scope declarations:
  • If the name is prefixed, the namespace is given by the in-scope declaration of the prefix.
  • If the name has no prefix, the namespace is the default namespace, if any, in scope. If there is no default namespace in scope, the added element has no namespace.
• As of Sirius Mods version 7.3, the InsertElementBefore method arguments may include only non-null EBCDIC characters that translate to Unicode. As of Sirius Mods version 7.6, these argument strings are Unicode or are converted to Unicode. For more information about the effects of this version 7.6 change, see "Strings and Unicode with the Xml API".
• When the return value of InsertElementBefore is not needed, you may want to Call it instead of saving its return value; the return value is typically needed only to add attributes or non-Text children of the Element.
• There is a very small "one-time" processing cost if certain XPath operations are performed after using this method, because Insert-Before methods are guaranteed to add a node out of document order. In general, processing an XmlDoc is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).

Example

In the following example, an element node with text is inserted as a sibling before node "b". An AddElement call then adds a child node to the parent of "b", and this child becomes a sibling of "b" located after it.

Begin %doc is Object XmlDoc %doc = New Call %doc:LoadXml('<top><a><c/><b>05</b></a></top>') %n1 is Object XmlNode %n2 is Object XmlNode %n1 = %doc:SelectSingleNode('top/a/b') Call %n1:InsertElementBefore('d', 'This comes before') %n2 = %n1:SelectSingleNode('..') Call %n2:AddElement('e', 'This comes after') Call %doc:Print('top') End

The example results follow:

<top> <a> <c/> <d>This comes before</d> <b>05</b> <e>This comes after</e> </a> </top>

note

The following fragment shows a way to insert a sibling node after the current node in cases where the document contents are not well known:

%nod2 = %nod1:SelectSingleNode('following-sibling::node()') If %nod2 Is Null Then %nod2 = %nod1:SelectSingleNode('..') Call %nod2:AddElement('foo') Else Call %nod2:InsertElementBefore('foo') End If

Request-Cancellation Errors

• Nod is the Root node.
• Nod is a child of the Root node and XmlDoc already has an Element.
• Argument name violates the rules for an XML element name.
• Name is prefixed, but the XmlDoc Namespace property is None.
• Name prefixed and Namespace On, but URI missing and no declaration for prefix in scope.
• Value violates the rules for an XML element value (that is, it contains an invalid character). Note that as of Sirius Mods version 7.6, this check can no longer be bypassed using the InvalidChar method &mdash; see "Usage Notes for the InvalidChar property".
• URI is invalid.
• URI is present, but the Namespace property is not On, or, URI is the null string and name is prefixed.
• Insufficient free space exists in CCATEMP.

See also

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods

• For more information about namespace declarations, see ?? refid=namsp..
• For more information about URIs, see ?? refid=nsuri..
• AddElement also adds an Element node. InsertElementBefore adds an Element as the immediately preceding sibling of the node pointed to by the method object; AddElement adds an Element as the last child of the node pointed to by the method object.
• These methods are useful for working with namespaces:
  • AddNamespace
  • SelectionNamespace