AddTopElement (XmlDoc function) - Revision history

JAL: insert < for < for self-closed element

2018-08-08T20:58:06Z

insert < for < for self-closed element

← Older revision		Revision as of 20:58, 8 August 2018
Line 49:		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><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 66:		Line 64:
	<p class="output"><nowiki><top>		<p class="output"><nowiki><top>
	<a>		<a>
	<b/>		<b/>
	</a>		</a>
	</top>		</top>
Line 74:		Line 72:
	<top>		<top>
	<a>		<a>
	<b/>		<b/>
	</a>		</a>
	</top>		</top>
Line 97:		Line 95:
	%doc = new		%doc = new

	%doc:loadXml('<top xmlns="http:mydata"><a><b/></a></top>')		%doc:loadXml('<top xmlns="http:mydata"><a><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 114:		Line 110:
	<p class="output"><nowiki><top xmlns="http:mydata">		<p class="output"><nowiki><top xmlns="http:mydata">
	<a>		<a>
	<b/>		<b/>
	</a>		</a>
	</top>		</top>
Line 122:		Line 118:
	<top xmlns="http:mydata">		<top xmlns="http:mydata">
	<a>		<a>
	<b/>		<b/>
	</a>		</a>
	</top>		</top>

JAL: minor formatting

2018-08-08T20:41:33Z

minor formatting

← Older revision		Revision as of 20:41, 8 August 2018
Line 1:		Line 1:
	{{Template:XmlDoc:AddTopElement subtitle}}		{{Template:XmlDoc:AddTopElement subtitle}}
	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>.		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==
Line 6:		Line 6:

	===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).</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 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7). </p></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> 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>

	<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>.		<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>.
	(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>		<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, [[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>		<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>		<p>
			<var>MoveNamespace</var> is available as of <var class="product">Sirius Mods</var> version 7.8. </p></td></tr>
	</table>		</table>

Line 85:		Line 91:

	===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 125:		Line 131:
	==Request-cancellation errors==		==Request-cancellation errors==
	<ul>		<ul>
	<li>The <var class="term">name</var> argument 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> <var>[[Namespace (XmlDoc property)\|Namespace]]</var> property value is <var>None</var>.
	<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><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>The <var class="term">uri</var> argument is invalid.
	<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><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>The <var>[[DeleteTopElement (XmlDoc subroutine)\|DeleteTopElement]]</var> subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>.		<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}}

JAL at 17:07, 3 March 2014

2014-03-03T17:07:54Z

← Older revision		Revision as of 17:07, 3 March 2014
Line 1:		Line 1:
	{{Template:XmlDoc:AddTopElement subtitle}}		{{Template:XmlDoc:AddTopElement subtitle}}
	The <var>AddTopElement </var> [[Notation_conventions_for_methods#Callable_methods\|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 class="syntaxTable">
Line 29:		Line 30:
	==Usage notes==		==Usage notes==
	<ul>		<ul>
	<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>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 76:		Line 78:
	<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 <var>MoveNamespace</var> 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\|Sirius Mods]]</var> Version 7.9 or greater.
Line 132:		Line 137:
	<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>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 [[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><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>The <var>[[DeleteTopElement (XmlDoc subroutine)\|DeleteTopElement]]</var> subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>.		<li>The <var>[[DeleteTopElement (XmlDoc subroutine)\|DeleteTopElement]]</var> subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>.

	<li>These methods are useful for working with namespaces:		<li>These methods are useful for working with namespaces:
	<ul>		<ul>
Line 140:		Line 148:
	</ul>		</ul>
	</ul>		</ul>

	{{Template:XmlDoc:AddTopElement footer}}		{{Template:XmlDoc:AddTopElement footer}}

JAL2: /* See also */

2012-06-19T21:31:41Z

JAL2: /* See also */

2012-06-19T21:30:15Z

JAL2: /* Syntax terms */

2012-06-10T22:30:48Z

Syntax terms

← Older revision		Revision as of 22:30, 10 June 2012
Line 14:		Line 14:

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

	<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:
Line 19:		Line 20:
	<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>.		<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>.
	(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>		(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>

	<tr><th><var>MoveNamespace</var></th>		<tr><th><var>MoveNamespace</var></th>
	<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.		<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.

JALWiccan: 1 revision

2012-06-10T22:20:40Z

1 revision

← Older revision	Revision as of 22:20, 10 June 2012
(No difference)

JAL2: /* Syntax terms */

2012-06-10T22:20:39Z

Syntax terms

← Older revision		Revision as of 22:20, 10 June 2012
Line 20:		Line 20:
	(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>		(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>
	<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>		<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>
	<p><var>MoveNamespace</var> is available as of <var class="product">Sirius Mods</var> version 7.8.</p></td></tr>		<p><var>MoveNamespace</var> is available as of <var class="product">Sirius Mods</var> version 7.8.</p></td></tr>

JAL2: /* Syntax terms */

2011-06-03T01:18:23Z

Syntax terms

← Older revision		Revision as of 01:18, 3 June 2011
Line 21:		Line 21:
	<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, 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.
	<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>'''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>

JAL2 at 19:38, 31 May 2011

2011-05-31T19:38:21Z

← Older revision		Revision as of 19:38, 31 May 2011
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 <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>.

	==Syntax==		==Syntax==
Line 17:		Line 17:
	<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> 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>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> 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>.
	(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>		(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>
	<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, 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.
	<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>'''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>
	</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>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.
	</ul>		</ul>
Line 74:		Line 74:
	<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===
Line 115:		Line 115:
	</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><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, but the <var>XmlDoc</var> <var>[[Namespace (XmlDoc property)\|Namespace]]</var> property value is <var>None</var>.
	<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 and <var>Namespace</var> is <var>On</var>, but <var class="term">uri</var> is missing.
	<li><var class="term">~~URI~~</var> is invalid.		<li>The <var class="term">uri</var> argument 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">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>Insufficient free space exists in CCATEMP.		<li>Insufficient free space exists in CCATEMP.
	</ul>		</ul>

← Older revision		Revision as of 21:31, 19 June 2012
Line 133:		Line 133:
	<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 [[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><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>The <var>[[DeleteTopElement]]</var> subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>.		<li>The <var>[[DeleteTopElement (XmlDoc subroutine)\|DeleteTopElement]]</var> subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>.
	<li>These methods are useful for working with namespaces:		<li>These methods are useful for working with namespaces:
	<ul>		<ul>

← Older revision		Revision as of 21:30, 19 June 2012
Line 133:		Line 133:
	<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 [[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><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>The <var>[[DeleteTopElement]]</var> subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>.
	<li>These methods are useful for working with namespaces:		<li>These methods are useful for working with namespaces:
	<ul>		<ul>