AddTopElement (XmlDoc function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (insert < for < for self-closed element)
 
(12 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:XmlDoc:AddTopElement subtitle}}
{{Template:XmlDoc:AddTopElement subtitle}}
The <var>AddTopElement </var> callable function adds an <var>Element</var> node as the new top-level element of the <var>XmlDoc</var> that is the object method.  This makes all the former children of the <var>XmlDoc</var> <var>Root</var> node become children of the new <var>Element</var>. <var>AddTopElement</var> also lets you specify the element namespace URI for the added <var>Element</var>.
The <var>AddTopElement </var> [[Notation conventions for methods#Callable methods|callable]] function adds an [[XmlDoc API#XmlDoc node types|Element node]] as the new top-level element of the <var>XmlDoc</var> that is the object method.  This makes all the former children of the <var>XmlDoc</var> <var>Root</var> node become children of the new <var>Element</var>. <var>AddTopElement</var> also lets you specify the element namespace URI for the added <var>Element</var>.


==Syntax==
==Syntax==
{{Template:XmlDoc:AddTopElement syntax}}
{{Template:XmlDoc:AddTopElement syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th>%nod</th>
<tr><th>%nod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the new top <var>Element</var> node that is added.</td></tr>
<td>If specified, an <var>XmlNode</var> that is set to point to the new top <var>Element</var> node that is added.</td></tr>
<tr><th>doc</th>
<tr><th>doc</th>
<td>An <var>XmlDoc</var> object variable.</td></tr>
<td>An <var>XmlDoc</var> object variable.</td></tr>
<tr><th>name</th>
<tr><th>name</th>
<td>The name (a <var>Unicode</var> string) to be given to the added <var>Element</var>. If the name is prefixed, a <var class="term">uri</var> argument must be provided.
<td>The name (a <var>Unicode</var> string) to be given to the added <var>Element</var>. If the name is prefixed, 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 version 7.9, and 100 characters prior to version 7.7). </p></td></tr>


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 <var class="product">[[Janus SOAP]]</var> Version 7.7). </td></tr>
<tr><th>uri</th>
<tr><th>uri</th>
<td>This optional, <var>Unicode</var> string, argument defaults to the null string:
<td>This optional, <var>Unicode</var> string, argument defaults to the null string:
<ul><li>If <var class="term">name</var> contains a prefix, then <var class="term">uri</var> specifies the URI (Uniform Resource Identifier) associated with that prefix for the element, so it must be a non-null string that is a valid URI.
<ul>
<li>If <var class="term">name</var> does not contain a prefix, then the old top element of the <var>XmlDoc</var> must be in a non-null default namespace, e.g., of the form <code><nowiki><nameWithoutPrefix xmlns="</nowiki><var class="term">uri</var>"></code>.
<li>If <var class="term">name</var> contains a prefix, then <var class="term">uri</var> specifies the URI (Uniform Resource Identifier) associated with that prefix for the element, so it must be a non-null string that is a valid URI. </li>
(Note: prior to version 7.9, <var class="term">uri</var> must be omitted or must be the null string if <var class="term">name</var> does not contain a prefix.)</ul></td></tr>
 
<li>If <var class="term">name</var> does not contain a prefix, then the old top element of the <var>XmlDoc</var> must be in a non-null default namespace, for example, of the form <code><nowiki><nameWithoutPrefix xmlns="</nowiki><var class="term">uri</var>"></code>.
<p class="note"><b>Note:</b> prior to version 7.9, <var class="term">uri</var> must be omitted or must be the null string if <var class="term">name</var> does not contain a prefix. </p></li>
</ul></td></tr>
 
<tr><th><var>MoveNamespace</var></th>
<tr><th><var>MoveNamespace</var></th>
<td>This optional, but [[Methods#Named parameters|name required]] argument is used to avoid a redundant namespace declaration on the old top element of the <var>XmlDoc</var>. If <code>MoveNamespace=True</code> and a <var class="term">uri</var> argument (with a non-null string) is provided, then if the "old" top element contains a namespace declaration which is the same as the declaration inserted due to the <var class="term">uri</var> argument, the declaration is deleted from the old top element.
<td>This optional, [[Methods#Named parameters|name required]] argument is used to avoid a redundant namespace declaration on the old top element of the <var>XmlDoc</var>. If <code>MoveNamespace=True</code> and a <var class="term">uri</var> argument (with a non-null string) is provided, then if the "old" top element contains a namespace declaration which is the same as the declaration inserted due to the <var class="term">uri</var> argument, the declaration is deleted from the old top element.
<p>Note: You should use <code>MoveNamespace=True</code> only when some consumer of the XML document cares about not having the redundant declaration. This would be an unusual situation, because the information content of the document does not change. Using <code>MoveNamespace=True</code> might trigger a scan of the entire <var>XmlDoc</var>, which <var>AddTopElement</var> does not normally do.</p></td></tr>
<p class="note">'''Note:''' You should use <code>MoveNamespace=True</code> only when some consumer of the XML document cares about not having the redundant declaration. This would be an unusual situation, because the information content of the document does not change. Using <code>MoveNamespace=True</code> might trigger a scan of the entire <var>XmlDoc</var>, which <var>AddTopElement</var> does not normally do.</p>
<p>
<var>MoveNamespace</var> is available as of <var class="product">Sirius Mods</var> version 7.8. </p></td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>If a <i>URI</i> argument is specified, the <var>XmlDoc</var>'s Namespace property must be <code>On</code>.
<li>If a <var class="term">uri</var> argument is specified, the <var>XmlDoc</var>'s <var>[[Namespace (XmlDoc property)|Namespace]]</var> property value must be <var>On</var>.</li>
<li>When you need to change the structure of an XML document and that need can be accomplished with <var>AddTopElement</var>, it is a more efficient approach than using <var>[[AddSubtree_(XmlDoc/XmlNode_function)|AddSubtree]]</var>.  See the [[#Examples|example]] below.
 
<li>When you need to change the structure of an XML document and that need can be accomplished with <var>AddTopElement</var>, it is a more efficient approach than using <var>[[AddSubtree_(XmlDoc/XmlNode_function)|AddSubtree]]</var>.  See the [[#Examples|example]] below. </li>
</ul>
</ul>


Line 38: Line 49:
   %doc = new
   %doc = new


   %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top><a><b/></a></top>')
   %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top><a>&lt;b/></a></top>')
   [[Notation_conventions_for_methods#Callable_methods|Call]] %doc:print
   [[Notation conventions for methods#Callable methods|Call]] %doc:print
   <nowiki>print '*********************'</nowiki>
   <nowiki>print '*********************'</nowiki>


   %doc2 = %doc:[[DeepCopy_(XmlDoc_function)|DeepCopy]]
   %doc2 = %doc:[[DeepCopy_(XmlDoc_function)|DeepCopy]]
   <nowiki>%doc2:addTopElement('soap:Body', -
   <nowiki>%doc2:addTopElement('soap:Body', 'http://schemas.xmlsoap.org/soap/envelope/')  
      'http://schemas.xmlsoap.org/soap/envelope/')
   %doc2:addTopElement('soap:Envelope', 'http://schemas.xmlsoap.org/soap/envelope/')</nowiki>
   %doc2:addTopElement('soap:Envelope', -
      'http://schemas.xmlsoap.org/soap/envelope/')</nowiki>


   call %doc2:print
   call %doc2:print
Line 55: Line 64:
<p class="output"><nowiki><top>
<p class="output"><nowiki><top>
   <a>
   <a>
       <b/>
       &lt;b/>
   </a>
   </a>
</top>
</top>
Line 63: Line 72:
       <top>
       <top>
         <a>
         <a>
             <b/>
             &lt;b/>
         </a>
         </a>
       </top>
       </top>
Line 73: Line 82:
<ul>
<ul>
<li>The order of the <var>AddTopElement</var> invocations is the reverse of the final order of the elements, that is, the second invocation creates the first element in the final document.
<li>The order of the <var>AddTopElement</var> invocations is the reverse of the final order of the elements, that is, the second invocation creates the first element in the final document.
<li>If you have no need to preserve the original <var>XmlDoc</var>, then both <var>AddTopElement</var> invocations can use <code>%doc</code> as the object method, and the <var>[[DeepCopy_(XmlDoc_function)|DeepCopy]]</var> can be omitted.
<li>If you have no need to preserve the original <var>XmlDoc</var>, then both <var>AddTopElement</var> invocations can use <code>%doc</code> as the object method, and the <var>[[DeepCopy_(XmlDoc_function)|DeepCopy]]</var> can be omitted.
<li>The redundant namespace declaration on the <code>soap:Body</code> element above would be deleted if the <code>MoveNamespace=True</code> argument is used, although usually the redundant declaration is acceptable and MoveNamespace should be avoided.
 
<li>The redundant namespace declaration on the <code>soap:Body</code> element above would be deleted if the <code>MoveNamespace=True</code> argument is used, although usually the redundant declaration is acceptable and <var>MoveNamespace</var> should be avoided.
</ul>
</ul>
===Add unprefixed SOAP wrappers===
===Add unprefixed SOAP wrappers===
The following example is similar, except that the SOAP elements use a default namespace declaration.  <var>AddTopElement</var> only allows this when the old top element is in a default namespace (here <code>http:mydata</code>).  Note that this example requires <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.9 or greater.
The following example is similar, except that the SOAP elements use a default namespace declaration.  <var>AddTopElement</var> only allows this when the old top element is in a default namespace (here <code>http:mydata</code>).  Note that this example requires <var class="product">Sirius Mods</var> Version 7.9 or greater.
<p class="code">begin
<p class="code">begin
   %doc is object xmlDoc
   %doc is object xmlDoc
Line 83: Line 95:
   %doc = new
   %doc = new


   %doc:loadXml('<top xmlns="http:mydata"><a><b/></a></top>')
   %doc:loadXml('<top xmlns="http:mydata"><a>&lt;b/></a></top>')
   call %doc:print
   call %doc:print
   <nowiki>print '*********************'</nowiki>
   <nowiki>print '*********************'</nowiki>


   <nowiki>%doc2 = %doc:deepCopy
   <nowiki>%doc2 = %doc:deepCopy
   %doc2:addTopElement('Body', -
   %doc2:addTopElement('Body', 'http://schemas.xmlsoap.org/soap/envelope/')
      'http://schemas.xmlsoap.org/soap/envelope/')
   %doc2:addTopElement('Envelope', 'http://schemas.xmlsoap.org/soap/envelope/')</nowiki>    
   %doc2:addTopElement('Envelope', -
      'http://schemas.xmlsoap.org/soap/envelope/')</nowiki>


   call %doc2:print
   call %doc2:print
Line 100: Line 110:
<p class="output"><nowiki><top xmlns="http:mydata">                                     
<p class="output"><nowiki><top xmlns="http:mydata">                                     
   <a>                                                       
   <a>                                                       
       <b/>                                                   
       &lt;b/>                                                   
   </a>                                                       
   </a>                                                       
</top>                                                       
</top>                                                       
Line 108: Line 118:
       <top xmlns="http:mydata">                               
       <top xmlns="http:mydata">                               
         <a>                                                 
         <a>                                                 
             <b/>                                             
             &lt;b/>                                             
         </a>                                                 
         </a>                                                 
       </top>                                                 
       </top>                                                 
Line 115: Line 125:
</nowiki></p>
</nowiki></p>


==Request-Cancellation Errors==
==Request-cancellation errors==
<ul>
<ul>
<li><var class="term">name</var> violates the rules for an XML element name.
<li>The <var class="term">name</var> argument violates the rules for an XML element name. </li>
<li><var class="term">name</var> is prefixed, but the <var>XmlDoc</var> Namespace property is <code>None</code>.
 
<li><var class="term">name</var> is prefixed and Namespace is <code>On</code>, but URI is missing.  
<li><var class="term">name</var> is prefixed, but the <var>XmlDoc</var> <var>[[Namespace (XmlDoc property)|Namespace]]</var> property value is <var>None</var>. </li>
<li><var class="term">URI</var> is invalid.
 
<li><var class="term">URI</var> is present, but the Namespace property is not <code>On</code>, or, <var class="term">URI</var> is the null string and <var class="term">name</var> is prefixed.
<li><var class="term">name</var> is prefixed and <var>Namespace</var> is <var>On</var>, but <var class="term">uri</var> is missing. </li>
<li>Insufficient free space exists in CCATEMP.
<li>The <var class="term">uri</var> argument is invalid. </li>
 
<li><var class="term">uri</var> is present, but the <var>Namespace</var> property value is not <var>On</var>, or, <var class="term">uri</var> is the null string and <var class="term">name</var> is prefixed. </li>
 
<li>Insufficient free space exists in CCATEMP. </li>
</ul>
</ul>


==See also==
==See also==
<ul>
<ul>
<li>For more information about namespace declarations, see [[XML_processing_in_Janus_SOAP#Names_and_namespaces|"Names and namespaces"]].
<li>For more information about namespace declarations, see [[XML processing in Janus SOAP#Names and namespaces|Names and namespaces]]. </li>
<li>For more information about URIs, see [[XML_processing_in_Janus_SOAP#Uniform_Resource_Identifier_syntax|"Uniform_Resource_Identifier_syntax"]].
 
<li><var>[[AddElement (XmlDoc/XmlNode function)|AddElement]]</var> and <var>[[InsertElementBefore (XmlNode function)|InsertElementBefore]]</var> also add an <var>Element</var> node.  <var>AddElement</var> adds an <var>Element</var> as the last child of the node pointed to by the method object; <var>InsertElementBefore</var> adds an <var>Element</var> as the immediately preceding sibling of the node pointed to by the method object.
<li>For more information about URIs, see [[XML processing in Janus SOAP#Uniform Resource Identifier syntax|Uniform Resource Identifier syntax]]. </li>
 
<li><var>[[AddElement (XmlDoc/XmlNode function)|AddElement]]</var> and <var>[[InsertElementBefore (XmlNode function)|InsertElementBefore]]</var> also add an <var>Element</var> node.  <var>AddElement</var> adds an <var>Element</var> as the last child of the node pointed to by the method object; <var>InsertElementBefore</var> adds an <var>Element</var> as the immediately preceding sibling of the node pointed to by the method object. </li>
 
<li>The <var>[[DeleteTopElement (XmlDoc subroutine)|DeleteTopElement]]</var> subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>. </li>
 
<li>These methods are useful for working with namespaces:  
<li>These methods are useful for working with namespaces:  
<ul>
<ul>
<li><var>[[AddNamespace (XmlNode subroutine)|AddNamespace]]</var>
<li><var>[[AddNamespace (XmlNode subroutine)|AddNamespace]]</var> </li>
<li><var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var>
<li><var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var> </li>
</ul>
</ul></li>
</ul>
</ul>
{{Template:XmlDoc:AddTopElement footer}}
{{Template:XmlDoc:AddTopElement footer}}

Latest revision as of 20:58, 8 August 2018

Add new top element to XmlDoc (XmlDoc class)

[Introduced in Sirius Mods 7.7; requires Janus SOAP]

The AddTopElement callable function adds an Element node as the new top-level element of the XmlDoc that is the object method. This makes all the former children of the XmlDoc Root node become children of the new Element. AddTopElement also lets you specify the element namespace URI for the added Element.

Syntax

[%nod =] doc:AddTopElement( name, [uri], [MoveNamespace= boolean])

Syntax terms

%nod If specified, an XmlNode that is set to point to the new top Element node that is added.
doc An XmlDoc object variable.
name The name (a Unicode string) to be given to the added Element. If the name is prefixed, 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 version 7.9, and 100 characters prior to version 7.7).

uri This optional, Unicode string, argument defaults to the null string:
  • If name contains a prefix, then uri specifies the URI (Uniform Resource Identifier) associated with that prefix for the element, so it must be a non-null string that is a valid URI.
  • If name does not contain a prefix, then the old top element of the XmlDoc must be in a non-null default namespace, for example, of the form <nameWithoutPrefix xmlns="uri">.

    Note: prior to version 7.9, uri must be omitted or must be the null string if name does not contain a prefix.

MoveNamespace This optional, name required argument is used to avoid a redundant namespace declaration on the old top element of the XmlDoc. If MoveNamespace=True and a uri argument (with a non-null string) is provided, then if the "old" top element contains a namespace declaration which is the same as the declaration inserted due to the uri argument, the declaration is deleted from the old top element.

Note: You should use MoveNamespace=True only when some consumer of the XML document cares about not having the redundant declaration. This would be an unusual situation, because the information content of the document does not change. Using MoveNamespace=True might trigger a scan of the entire XmlDoc, which AddTopElement does not normally do.

MoveNamespace is available as of Sirius Mods version 7.8.

Usage notes

  • If a uri argument is specified, the XmlDoc's Namespace property value must be On.
  • When you need to change the structure of an XML document and that need can be accomplished with AddTopElement, it is a more efficient approach than using AddSubtree. See the example below.

Examples

Add prefixed SOAP wrappers

The following request makes a copy of an XML document, then adds "SOAP wrappers" to it:

begin %doc is object xmlDoc %doc2 is object xmlDoc %doc = new %doc:loadXml('<top><a><b/></a></top>') Call %doc:print print '*********************' %doc2 = %doc:DeepCopy %doc2:addTopElement('soap:Body', 'http://schemas.xmlsoap.org/soap/envelope/') %doc2:addTopElement('soap:Envelope', 'http://schemas.xmlsoap.org/soap/envelope/') call %doc2:print end

The result is:

<top> <a> <b/> </a> </top> ********************* <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <top> <a> <b/> </a> </top> </soap:Body> </soap:Envelope>

In the example:

  • The order of the AddTopElement invocations is the reverse of the final order of the elements, that is, the second invocation creates the first element in the final document.
  • If you have no need to preserve the original XmlDoc, then both AddTopElement invocations can use %doc as the object method, and the DeepCopy can be omitted.
  • The redundant namespace declaration on the soap:Body element above would be deleted if the MoveNamespace=True argument is used, although usually the redundant declaration is acceptable and MoveNamespace should be avoided.

Add unprefixed SOAP wrappers

The following example is similar, except that the SOAP elements use a default namespace declaration. AddTopElement only allows this when the old top element is in a default namespace (here http:mydata). Note that this example requires Sirius Mods Version 7.9 or greater.

begin %doc is object xmlDoc %doc2 is object xmlDoc %doc = new %doc:loadXml('<top xmlns="http:mydata"><a><b/></a></top>') call %doc:print print '*********************' %doc2 = %doc:deepCopy %doc2:addTopElement('Body', 'http://schemas.xmlsoap.org/soap/envelope/') %doc2:addTopElement('Envelope', 'http://schemas.xmlsoap.org/soap/envelope/') call %doc2:print end

The result is:

<top xmlns="http:mydata"> <a> <b/> </a> </top> ********************* <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"> <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/"> <top xmlns="http:mydata"> <a> <b/> </a> </top> </Body> </Envelope>

Request-cancellation errors

  • The name argument violates the rules for an XML element name.
  • name is prefixed, but the XmlDoc Namespace property value is None.
  • name is prefixed and Namespace is On, but uri is missing.
  • The uri argument is invalid.
  • uri is present, but the Namespace property value is not On, or, uri is the null string and name is prefixed.
  • Insufficient free space exists in CCATEMP.

See also