Difference between revisions of "InsertElementBefore (XmlNode function)"

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (move footer template to actual end; edits, tags and links)
Line 1: Line 1:
 
{{Template:XmlNode:InsertElementBefore subtitle}}
 
{{Template:XmlNode:InsertElementBefore subtitle}}
 +
The <var>InsertElementBefore</var> <var>[[Notation_conventions_for_methods#Callable_methods|Callable-function]]</var> inserts an <var>Element</var> node as the sibling immediately preceding the method <var>XmlNode</var>.  <var>InsertElementBefore</var> also lets you add a <var>Text</var> node as the child of the inserted  <var>Element</var>, and it lets you specify the namespace URI for the inserted element.
  
This callable function inserts an Element node as the
 
sibling immediately preceding the method <var>XmlNode</var>.
 
<var>InsertElementBefore</var> 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==
 
==Syntax==
 
{{Template:XmlNode:InsertElementBefore syntax}}
 
{{Template:XmlNode:InsertElementBefore syntax}}
Line 10: Line 7:
 
<table class="syntaxTable">
 
<table class="syntaxTable">
 
<tr><th>%outNod</th>
 
<tr><th>%outNod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the Element node that is inserted. </td></tr>
+
<td>If specified, an <var>XmlNode</var> that is set to point to the <var>Element</var> node that is inserted.</td></tr>
 
<tr><th>nod</th>
 
<tr><th>nod</th>
<td><var>XmlNode</var> that points to the (non-Root) node before which the Element node is inserted. </td></tr>
+
<td><var>XmlNode</var> that points to the (non-Root) node before which the <var>Element</var> node is inserted.</td></tr>
 
<tr><th>name</th>
 
<tr><th>name</th>
<td>A <var>Unicode</var> string that is the name of the inserted Element; if prefixed, the prefix must be declared, or a <var class="term">uri</var> 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 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7). </td></tr>
+
<td>A <var>Unicode</var> string that is the name of the inserted <var>Element</var>; if prefixed, the prefix must be declared, or a <var class="term">uri</var> argument must be provided.<p>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 300 characters (127 characters prior to <var class="product">[[Sirius Mods]]</var> Version 7.9, and 100 characters prior to Version 7.7).</p></td></tr>
 
<tr><th>value</th>
 
<tr><th>value</th>
<td>This optional argument is the content of a Text node that is added as a child of the inserted element. This <var>Unicode</var> string content is stored without any normalization, entity substitution, etc.
+
<td>This optional argument is the content of a <var>Text</var> node that is added as a child of the inserted element. This <var>Unicode</var> string content is stored without any normalization, entity substitution, etc.<p>Since <var>Text</var> nodes cannot contain the null string, this argument is ignored if it is the null string.</p></td></tr>
 
+
<tr><th>URI</th>
Since Text nodes cannot contain the null string, this argument is ignored if it is the null string. </td></tr>
 
<tr><th><var>URI</var></th>
 
 
<td>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.</td></tr>
 
<td>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.</td></tr>
 
</table>
 
</table>
Line 25: Line 20:
 
==Usage notes==
 
==Usage notes==
 
<ul>
 
<ul>
<li>If a <i>URI</i> argument is specified, the <var>XmlDoc</var>'s Namespace property
+
<li>If a <var class="term">URI</var> argument is specified, the <var>XmlDoc</var>'s Namespace property must be <code>On</code>, and <var class="term">URI</var> must either be the null string, or it must have the format of an absolute URI. The effect depends on whether the <i>name</i> value includes a prefix:
must be <tt>On</tt>, and <i>URI</i> must either
 
be the null string, or it must have the format of an absolute URI.
 
The effect depends on whether the <i>name</i> value includes
 
a prefix:
 
 
<ul>
 
<ul>
<li>If <i>name</i> has a prefix, <i>URI</i> must '''not''' be
+
<li>If <var class="term">name</var> has a prefix, <var class="term">URI</var> must '''not''' be the null string, and <var class="term">URI</var> is the declared namespace URI associated with that prefix and added element.
the null string, and <i>URI</i> is the declared namespace URI
+
<li>If <var class="term">name</var> does not have a prefix:
associated with that prefix and added element.
 
<li>If <i>name</i> does not have a prefix:
 
 
<ul>
 
<ul>
<li>If <i>URI</i> is the null string,
+
<li>If <var class="term">URI</var> 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.
the added element does not have a default namespace.
+
<li>If <var class="term">URI</var> is '''not''' the null string, the added element has <var class="term">URI</var> as the default namespace.
Any in-scope default namespace the added element might have inherited,
 
is not inherited.
 
<li>If <i>URI</i> is '''not''' the null string,
 
the added element has <i>URI</i> as the default namespace.
 
 
</ul>
 
</ul>
 
</ul>
 
</ul>
 
+
If a non-null string <var class="term">URI</var> 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 a non-null string <i>URI</i> argument is provided, and the namespace
+
<li>If the <var class="term">URI</var> argument is '''not''' present, the added element's namespace is determined by the prefix and in-scope declarations:
declaration resulting from it is not in scope for the added element, then
 
a namespace declaration is added at that element.
 
<li>If the <i>URI</i> argument is '''not''' present, the added element's namespace
 
is determined by the prefix and in-scope declarations:
 
 
<ul>
 
<ul>
<li>If the <i>name</i> is prefixed, the namespace is given by the
+
<li>If the <var class="term">name</var> is prefixed, the namespace is given by the in-scope declaration of the prefix.
in-scope declaration of the prefix.
+
<li>If the <var class="term">name</var> 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.
<li>If the <i>name</i> 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.
 
 
</ul>
 
</ul>
<li>As of <var class="product">Sirius Mods</var> version 7.3, the <var>InsertElementBefore</var> method arguments may
+
<li>As of <var class="product">Sirius Mods</var> Version 7.3, the <var>InsertElementBefore</var> method arguments may include only non-null EBCDIC characters that translate to <var>Unicode</var>. As of <var class="product">Sirius Mods</var> Version 7.6, these argument strings are <var>Unicode</var> or are converted to <var>Unicode</var>. For more information about the effects of this Version 7.6 change, see [[XmlDoc API#Strings and Unicode with the XmlDoc API|"Strings and Unicode with the Xml API"]].
include only non-null EBCDIC characters that translate to <var>Unicode</var>.
+
<li>When the return value of <var>InsertElementBefore</var> is not needed, you may want to <var>Call</var> it instead of saving its return value; the return value is typically needed only to add attributes or non-Text children of the <var>Element</var>.
As of <var class="product">Sirius Mods</var> version 7.6, these argument strings are <var>Unicode</var> or are
+
<li>There is a very small "one-time" processing cost if certain [[XPath#XPath_syntax|Xpath expression]] 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 <var>XmlDoc</var> is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
converted to <var>Unicode</var>.
 
For more information about the effects of this version 7.6
 
change, see [[XmlDoc API#Strings and Unicode with the XmlDoc API|"Strings and Unicode with the Xml API"]].
 
<li>When the return value of <var>InsertElementBefore</var> 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.
 
<li>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 <var>XmlDoc</var> is likely to be more efficient if
 
you add nodes in document order (that is, top-to-bottom, left-to-right).
 
 
</ul>
 
</ul>
  
 
==Examples==
 
==Examples==
 
+
<ol><li>In the following example, an element node with text is inserted as a sibling before node "b". An <var>AddElement</var> call then adds a child node to the parent of "b", and this child becomes a sibling of "b" located after it.
In the following example, an element node with text is inserted as a sibling
+
<p class="code">begin
before node "b".
+
  %doc is object xmlDoc
An AddElement call then adds
+
  %doc = new
a child node to the parent of "b", and this child becomes
+
  [[Notation_conventions_for_methods#Callable_methods|call]] %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top><a><c/><nowiki><b>05</b></nowiki></a></top>')
a sibling of "b" located after it.
+
  %n1 is object xmlNode
<p class="code">Begin
+
  %n2 is object xmlNode
%doc is Object XmlDoc
+
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a/b')
%doc = New
+
  call %n1:insertElementBefore('d', 'This comes before')
Call %doc:LoadXml('<top><a><c/><nowiki><b>05</b></nowiki></a></top>')
+
  %n2 = %n1:selectSingleNode('..')
%n1 is Object XmlNode
+
  call %n2:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('e', 'This comes after')
%n2 is Object XmlNode
+
  call %doc:[[Print_(XmlDoc/XmlNode_subroutine)|print]]('top')
%n1 = %doc:SelectSingleNode('top/a/b')
+
end
Call %n1:InsertElementBefore('d', 'This comes before')
 
%n2 = %n1:SelectSingleNode('..')
 
Call %n2:AddElement('e', 'This comes after')
 
Call %doc:Print('top')
 
End
 
 
</p>
 
</p>
 
 
The example results follow:
 
The example results follow:
 
<p class="code"><top>
 
<p class="code"><top>
Line 106: Line 65:
 
</top>
 
</top>
 
</p>
 
</p>
:note
+
<li>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:
The following fragment shows a way to
+
<p class="code">%nod2 = %nod1:selectSingleNode('following-sibling::node()')
insert a sibling node ''after'' the current node
+
if %nod2 is null Then
in cases where the document contents are not well known:
+
%nod2 = %nod1:aelectSingleNode('..')
<p class="code">%nod2 = %nod1:SelectSingleNode('following-sibling::node()')
+
   call %nod2:addElement('foo')
If %nod2 Is Null Then
+
else
%nod2 = %nod1:SelectSingleNode('..')
+
   call %nod2:insertElementBefore('foo')
   Call %nod2:AddElement('foo')
+
end if
Else
+
</p></ol>
   Call %nod2:InsertElementBefore('foo')
 
End If
 
</p>
 
  
 
==Request-Cancellation Errors==
 
==Request-Cancellation Errors==
 
<ul>
 
<ul>
<li><i>Nod</i> is the Root node.
+
<li><var class="term">Nod</var> is the <var>Root</var> node.
<li><i>Nod</i> is a child of
+
<li><var class="term">Nod</var> is a child of the <var>Root</var> node and <var>XmlDoc</var> already has an <var>Element</var>.
the Root node and <var>XmlDoc</var> already has an Element.
+
<li>Argument <var class="term">name</var> violates the rules for an XML element name.
<li>Argument <i>name</i> violates the rules for an XML element name.
+
<li><var class="term">Name</var> is prefixed, but the <var>XmlDoc</var> Namespace property is <code>None</code>.
<li><i>Name</i> is prefixed, but the <var>XmlDoc</var> Namespace property
+
<li>Argument <var class="term">name</var> prefixed and Namespace On, but URI missing and no declaration for prefix in scope.
is None.
+
<li><var class="term">Value</var> violates the rules for an XML element value (that is, it contains an invalid character).<p>Note that as of <var class="product">Sirius Mods</var> version 7.6, this check can no longer be bypassed using the <var>[[InvalidChar_(XmlDoc_property)|InvalidChar]]</var> method &mdash; see [[InvalidChar (XmlDoc property)#Usage notes|"Usage Notes for the InvalidChar property"]].</p>
<li><i>Name</i> prefixed and Namespace On, but URI missing and no
+
<li><var class="term">URI</var> is invalid.
declaration for prefix in scope.
+
<li><var class="term">URI</var> is present, but the Namespace property is not <code>On</code>,
<li><i>Value</i> violates the rules for an
+
or, <var class="term">URI</var> is the null string and <var class="term">name</var> is prefixed.
XML element value (that is, it contains an invalid character).
 
Note that as of
 
<var class="product">Sirius Mods</var> version 7.6, this check can no longer be bypassed using the InvalidChar
 
method &amp;amp;mdash; see [[InvalidChar (XmlDoc property)#Usage notes|"Usage Notes for the InvalidChar property"]].
 
<li><i>URI</i> is invalid.
 
<li><i>URI</i> is present, but the
 
Namespace property is not <tt>On</tt>,
 
or, <i>URI</i> is the null string and <i>name</i> is prefixed.
 
 
<li>Insufficient free space exists in CCATEMP.
 
<li>Insufficient free space exists in CCATEMP.
 
</ul>
 
</ul>
  
 
==See also==
 
==See also==
{{Template:XmlNode:InsertElementBefore footer}}
 
 
 
<ul>
 
<ul>
<li>For more information about
+
<li>For more information about namespace declarations, see [[XML processing in Janus SOAP#Names and namespaces|"Names and namespaces"]].
namespace declarations, see [[??]] refid=namsp..
+
<li>For more information about URIs, see [[XML_processing_in_Janus_SOAP#Uniform_Resource_Identifier_syntax|"Uniform_Resource Identifier syntax"]].
<li>For more information about URIs, see [[??]] refid=nsuri..
+
<li><var>[[AddElement (XmlDoc/XmlNode function)|AddElement]]</var> also adds an <var>Element</var> node. <var>InsertElementBefore</var> adds an <var>Element</var> as the immediately preceding sibling of the node pointed to by the method object; <var>AddElement</var> adds an <var>Element</var> as the last child of the node pointed to by the method object.
<li>[[AddElement (XmlDoc/XmlNode function)|AddElement]]
 
also adds an Element node.
 
<var>InsertElementBefore</var> 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.
 
 
<li>These methods are useful for working with namespaces:
 
<li>These methods are useful for working with namespaces:
 
<ul>
 
<ul>
<li>[[AddNamespace (XmlNode subroutine)|AddNamespace]]
+
<li><var>[[AddNamespace (XmlNode subroutine)|AddNamespace]]</var>
<li>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]
+
<li><var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var>
 
</ul>
 
</ul>
 
</ul>
 
</ul>
 +
{{Template:XmlNode:InsertElementBefore footer}}

Revision as of 02:13, 28 May 2011

Insert an Element before this node (XmlNode class)

[Requires Janus SOAP]

The InsertElementBefore 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 300 characters (127 characters prior to Sirius Mods Version 7.9, and 100 characters prior to Version 7.7).

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 expression 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).

Examples

  1. 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>

  2. 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:aelectSingleNode('..') 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.
  • Argument 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 — 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