AddElement (XmlDoc/XmlNode function) - Revision history

ELowell: /* Syntax terms */

2015-09-02T21:00:48Z

Syntax terms

← Older revision		Revision as of 21:00, 2 September 2015
Line 6:		Line 6:
	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>%nod</th>		<tr><th nowrap>%nod</th>
	<td>If specified, an <var>XmlNode</var> that is set to point to the Element node that is added. </td></tr>		<td>If specified, an <var>XmlNode</var> that is set to point to the Element node that is added. </td></tr>
	<tr><th>nr</th>		<tr><th>nr</th>

JAL at 02:02, 1 March 2014

2014-03-01T02:02:59Z

← Older revision		Revision as of 02:02, 1 March 2014
Line 1:		Line 1:
	{{Template:XmlDoc/XmlNode:AddElement subtitle}}		{{Template:XmlDoc/XmlNode:AddElement subtitle}}
	This [[Notation_conventions_for_methods#Callable_methods\|callable]] function adds an ~~<var>~~Element~~</var>~~ node as the last child of the <var>Root</var> node or <var>Element</var> node referenced by the method object. <var>AddElement</var> also lets you add a <var>Text</var> node as the child of the added <var>Element</var>, and lets you specify the namespace URI for the added element.		This [[Notation_conventions_for_methods#Callable_methods\|callable]] function adds an [[XmlDoc API#XmlDoc node types\|Element node]] as the last child of the <var>Root</var> node or <var>Element</var> node referenced by the method object. <var>AddElement</var> also lets you add a <var>Text</var> node as the child of the added <var>Element</var>, and lets you specify the namespace URI for the added element.

	==Syntax==		==Syntax==
Line 172:		Line 172:

	==Request-cancellation errors==		==Request-cancellation errors==
			This list is not exhaustive: it does <i>not</i> include all the errors that are request cancelling.
	<ul>		<ul>
	<li>The <var class="term">nr</var> object is neither the <var>Root</var> nor an <var>Element</var> node.		<li>The <var class="term">nr</var> object is neither the <var>Root</var> nor an <var>Element</var> node.

JAL: /* Adding characters that are represented by character references */

2012-11-06T18:59:03Z

Adding characters that are represented by character references

← Older revision		Revision as of 18:59, 6 November 2012
Line 86:		Line 86:
	<ul>		<ul>
	<li>The first <var>AddElement</var> invocation uses the <var>[[EbcdicToUnicode (String function)\|EbcdicToUnicode]]</var> function and parameter setting that decode and convert a character reference to <var>Unicode</var>.		<li>The first <var>AddElement</var> invocation uses the <var>[[EbcdicToUnicode (String function)\|EbcdicToUnicode]]</var> function and parameter setting that decode and convert a character reference to <var>Unicode</var>.

	<li>The second <var>AddElement</var> invocation uses the [[U (String function)\|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.		<li>The second <var>AddElement</var> invocation uses the [[U (String function)\|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.
	<li>The third and fourth <var>AddElement</var> invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (<code>&</code>) is translated on output to a character reference (<code>&</code>).
			<li>The third and fourth <var>AddElement</var> invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (<code>&</code>) is translated on output to a character reference (<code>&amp;</code>).

	<li>The fifth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the [[XML processing in Janus SOAP#Entity references\|entity reference]] for the copyright character.		<li>The fifth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the [[XML processing in Janus SOAP#Entity references\|entity reference]] for the copyright character.

	<li>The sixth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the [[Print_(XmlDoc/XmlNode_subroutine)\|Print]] method displays its XML hexadecimal character reference.		<li>The sixth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the [[Print_(XmlDoc/XmlNode_subroutine)\|Print]] method displays its XML hexadecimal character reference.
	</ul>		</ul>
Line 94:		Line 98:
	%doc is object xmlDoc auto new		%doc is object xmlDoc auto new
	%doc:[[LoadXml_(XmlDoc/XmlNode_function)\|loadXml]]('<top/>')		%doc:[[LoadXml_(XmlDoc/XmlNode_function)\|loadXml]]('<top/>')
	%n is object ~~xXmlNode~~		%n is object XmlNode

	%n = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)\|selectSingleNode]]('top')		%n = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)\|selectSingleNode]]('top')
Line 100:		Line 104:
	'&#xA9;':[[EbcdicToUnicode (String function)\|ebcdicToUnicode]](CharacterDecode=True))		'&#xA9;':[[EbcdicToUnicode (String function)\|ebcdicToUnicode]](CharacterDecode=True))
	%n:addElement('a2', '&#xA9;':U)		%n:addElement('a2', '&#xA9;':U)
	%n:addElement('a3', '&#xA9;':EbcdicToUnicode		%n:addElement('a3', '&amp;#xA9;':EbcdicToUnicode)
	%n:addElement('a4', '&#xA9;')		%n:addElement('a4', '&#xA9;')
	%n:addElement('a5', '&copy;':U)		%n:addElement('a5', '&copy;':U)
Line 111:		Line 115:
	The example result follows:		The example result follows:
	<p class="output"><top>		<p class="output"><top>
	<a1>~~©~~</a1>		<a1>©</a1>
	<a2>~~©~~</a2>		<a2>©</a2>
	<a3>©</a3>		<a3>&amp;amp;#xA9;</a3>
	<a4>©</a4>		<a4>&amp;#xA9;</a4>
	<a5>~~©~~</a5>		<a5>©</a5>
	<a6>&#x2122;</a6>		<a6>&#x2122;</a6>
	</top>		</top>
	</p>		</p>

JALWiccan: 1 revision

2012-11-06T18:22:48Z

1 revision

← Older revision	Revision as of 18:22, 6 November 2012
(No difference)

JAL2: /* Adding characters that are represented by character references */

2012-11-06T18:22:37Z

Adding characters that are represented by character references

← Older revision		Revision as of 18:22, 6 November 2012
Line 87:		Line 87:
	<li>The first <var>AddElement</var> invocation uses the <var>[[EbcdicToUnicode (String function)\|EbcdicToUnicode]]</var> function and parameter setting that decode and convert a character reference to <var>Unicode</var>.		<li>The first <var>AddElement</var> invocation uses the <var>[[EbcdicToUnicode (String function)\|EbcdicToUnicode]]</var> function and parameter setting that decode and convert a character reference to <var>Unicode</var>.
	<li>The second <var>AddElement</var> invocation uses the [[U (String function)\|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.		<li>The second <var>AddElement</var> invocation uses the [[U (String function)\|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.
	<li>The third and fourth <var>AddElement</var> invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (<code>&</code>) is translated on output to a character reference (<code>&~~amp;amp;~~</code>).		<li>The third and fourth <var>AddElement</var> invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (<code>&</code>) is translated on output to a character reference (<code>&</code>).
	<li>The fifth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the [[XML processing in Janus SOAP#Entity references\|entity reference]] for the copyright character.		<li>The fifth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the [[XML processing in Janus SOAP#Entity references\|entity reference]] for the copyright character.
	<li>The sixth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the [[Print_(XmlDoc/XmlNode_subroutine)\|Print]] method displays its XML hexadecimal character reference.		<li>The sixth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the [[Print_(XmlDoc/XmlNode_subroutine)\|Print]] method displays its XML hexadecimal character reference.
Line 113:		Line 113:
	<a1>©</a1>		<a1>©</a1>
	<a2>©</a2>		<a2>©</a2>
	<a3>&~~amp;amp;~~#xA9;</a3>		<a3>©</a3>
	<a4>&~~amp;amp;~~#xA9;</a4>		<a4>©</a4>
	<a5>©</a5>		<a5>©</a5>
	<a6>&#x2122;</a6>		<a6>&#x2122;</a6>

JAL2: /* Adding characters that are represented by character references */

2011-05-27T16:00:34Z

Adding characters that are represented by character references

← Older revision		Revision as of 16:00, 27 May 2011
Line 81:		Line 81:
	</ol>		</ol>
	====Adding characters that are represented by character references====		====Adding characters that are represented by character references====
	For a <var class="product">[[Sirius Mods~~\|Sirius Mods]]~~</var> Version 7.6 or higher request, the following example shows techniques for adding an <var>Element</var> node that contains a Unicode "copyright" character, and it also includes a statement to add a "trademark" character.		For a <var class="product">Sirius Mods</var> Version 7.6 or higher request, the following example shows techniques for adding an <var>Element</var> node that contains a Unicode "copyright" character, and it also includes a statement to add a "trademark" character.

	The <var>AddElement</var> statements use a hex character reference or an entity reference to represent the copyright character, and they use a character reference for the trademark. Those references must first be decoded so <var>AddElement</var> will interpret the value string as a single character and not as several individual characters.		The <var>AddElement</var> statements use a hex character reference or an entity reference to represent the copyright character, and they use a character reference for the trademark. Those references must first be decoded so <var>AddElement</var> will interpret the value string as a single character and not as several individual characters.
Line 119:		Line 119:
	</top>		</top>
	</p>		</p>

	====Working with URIs====		====Working with URIs====
	The following example contains several <var>AddElement</var> invocations and shows the effects of the <var class="term">uri</var> argument:		The following example contains several <var>AddElement</var> invocations and shows the effects of the <var class="term">uri</var> argument:

JAL2 at 15:59, 27 May 2011

2011-05-27T15:59:44Z

Show changes

Dme: /* Syntax terms */

2011-05-22T20:43:28Z

Syntax terms

← Older revision		Revision as of 20:43, 22 May 2011
Line 15:		Line 15:
	Multiple Elements with the same name may be added to a single parent Element.		Multiple Elements with the same name may be added to a single parent Element.

	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]]~~). </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 prior to version 7.9, and 100 characters prior to Version 7.7). </td></tr>
	<tr><th>value</th>		<tr><th>value</th>
	<td>This optional argument is the content of a <var>Text</var> node that is added as a child of the added element. This 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 added element. This content is stored without any normalization, entity substitution, etc.

JALWiccan: 1 revision

2011-05-04T17:45:37Z

1 revision

← Older revision	Revision as of 17:45, 4 May 2011
(No difference)

Goff: move footer template to actual end (otherwise subsequent intervening text gets omitted), tags and links

2011-05-04T17:45:36Z

move footer template to actual end (otherwise subsequent intervening text gets omitted), tags and links

← Older revision		Revision as of 17:45, 4 May 2011
Line 43:		Line 43:
	<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 <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.
	</ul>		</ul>
	<li>As of <var class="product">[[Sirius Mods\|"Sirius Mods"]]</var> Version 7.3, the <var>AddElement</var> arguments may include only non-null EBCDIC characters that translate to Unicode. 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>.		<li>As of <var class="product">[[Sirius Mods\|Sirius Mods]]</var> Version 7.3, the <var>AddElement</var> arguments may include only non-null EBCDIC characters that translate to Unicode. 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 XmlDoc API"]]. For a Unicode-specific <var>Add Element</var> example, see [[#Adding characters that are represented by character references\|"Adding characters that are represented by character references"]].		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 XmlDoc API"]]. For a Unicode-specific <var>Add Element</var> example, see [[#Adding characters that are represented by character references\|"Adding characters that are represented by character references"]].
Line 81:		Line 81:
	</ol>		</ol>
	====Adding characters that are represented by character references====		====Adding characters that are represented by character references====
	<ol><li>For a <var class="product">[[Sirius Mods\|"Sirius Mods"]]</var> Version 7.6 or higher request, the following example shows techniques for adding an <var>Element</var> node that contains a Unicode "copyright" character, and it also includes a statement to add a "trademark" character.		<ol><li>For a <var class="product">[[Sirius Mods\|Sirius Mods]]</var> Version 7.6 or higher request, the following example shows techniques for adding an <var>Element</var> node that contains a Unicode "copyright" character, and it also includes a statement to add a "trademark" character.

	The <var>AddElement</var> statements use a hex character reference or an entity reference to represent the copyright character, and they use a character reference for the trademark. Those references must first be decoded so <var>AddElement</var> will interpret the value string as a single character and not as several individual characters.		The <var>AddElement</var> statements use a hex character reference or an entity reference to represent the copyright character, and they use a character reference for the trademark. Those references must first be decoded so <var>AddElement</var> will interpret the value string as a single character and not as several individual characters.
Line 87:		Line 87:
	<li>The first <var>AddElement</var> invocation uses the <var>[[EbcdicToUnicode (String function)\|EbcdicToUnicode]]</var> function and parameter setting that decode and convert a character reference to <var>Unicode</var>.		<li>The first <var>AddElement</var> invocation uses the <var>[[EbcdicToUnicode (String function)\|EbcdicToUnicode]]</var> function and parameter setting that decode and convert a character reference to <var>Unicode</var>.
	<li>The second <var>AddElement</var> invocation uses the [[U (String function)\|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.		<li>The second <var>AddElement</var> invocation uses the [[U (String function)\|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.
	<li>The third and fourth <var>AddElement</var> invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (<code>&</code>) is translated on output to a character reference (<code>&amp;</code>).		<li>The third and fourth <var>AddElement</var> invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (<code>&</code>) is translated on output to a character reference (<code>&amp;amp;</code>).
	<li>The fifth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the [[XML processing in Janus SOAP#Entity references\|entity reference]] for the copyright character.		<li>The fifth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the [[XML processing in Janus SOAP#Entity references\|entity reference]] for the copyright character.
	<li>The sixth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the [[Print_(XmlDoc/XmlNode_subroutine)\|Print]] method displays its XML hexadecimal character reference.		<li>The sixth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the [[Print_(XmlDoc/XmlNode_subroutine)\|Print]] method displays its XML hexadecimal character reference.
Line 98:		Line 98:
	%n = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)\|selectSingleNode]]('top')		%n = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)\|selectSingleNode]]('top')
	%n:addElement('a1', -		%n:addElement('a1', -
	'&#xA9;':[[EbcdicToUnicode (String function)\|ebcdicToUnicode]](CharacterDecode=True))		'&amp;#xA9;':[[EbcdicToUnicode (String function)\|ebcdicToUnicode]](CharacterDecode=True))
	%n:addElement('a2', '&#xA9;':U)		%n:addElement('a2', '&amp;#xA9;':U)
	%n:addElement('a3', '&#xA9;':EbcdicToUnicode		%n:addElement('a3', '&amp;#xA9;':EbcdicToUnicode
	%n:addElement('a4', '&#xA9;')		%n:addElement('a4', '&amp;#xA9;')
	%n:addElement('a5', '&copy;':U)		%n:addElement('a5', '&amp;copy;':U)
	%n:addElement('a6', '&#x2122;':U)		%n:addElement('a6', '&amp;#x2122;':U)

	%doc:[[Print_(XmlDoc/XmlNode_subroutine)\|print]]		%doc:[[Print_(XmlDoc/XmlNode_subroutine)\|print]]
Line 111:		Line 111:
	The example result follows:		The example result follows:
	<p class="output"><top>		<p class="output"><top>
	<a1>&copy.</a1>		<a1>&copy.</a1>
	<a2>&copy.</a2>		<a2>&copy.</a2>
	<a3>&amp;#xA9;</a3>		<a3>&amp;amp;#xA9;</a3>
	<a4>&amp;#xA9;</a4>		<a4>&amp;amp;#xA9;</a4>
	<a5>&copy.</a5>		<a5>&copy.</a5>
	<a6>&#x2122;</a6>		<a6>&amp;#x2122;</a6>
	</top>		</top>
	</p></ol>		</p></ol>
Line 124:		Line 124:
	<li>An initial invocation of <var>AddElement</var> adds the first element of the document. The method object in this case is an <var>XmlDoc</var>. This invocation fails if the document already contains an element node.		<li>An initial invocation of <var>AddElement</var> adds the first element of the document. The method object in this case is an <var>XmlDoc</var>. This invocation fails if the document already contains an element node.
	<li>A second <var>AddElement</var> invocation, this time with a node as the method object, adds an element as the child of the first element. This second element has a prefixed name but no <var class="term">URI</var> value. Since the prefix matches that of the parent element, the second element receives the namespace URI of the first.		<li>A second <var>AddElement</var> invocation, this time with a node as the method object, adds an element as the child of the first element. This second element has a prefixed name but no <var class="term">URI</var> value. Since the prefix matches that of the parent element, the second element receives the namespace URI of the first.
	<li>A third <var>AddElement</var> invocation adds an element (to the first). Although the <var>AddElement</var> arguments include no name prefix and no <var class="term">URI</var>, the added element may still be associated with a namespace — the default namespace of its nearest ancestor. In this case, however, no default namespace is in scope (the parent's namespace is associated with its prefix), so this child has no namespace association at all.		<li>A third <var>AddElement</var> invocation adds an element (to the first). Although the <var>AddElement</var> arguments include no name prefix and no <var class="term">URI</var>, the added element may still be associated with a namespace &mdash; the default namespace of its nearest ancestor. In this case, however, no default namespace is in scope (the parent's namespace is associated with its prefix), so this child has no namespace association at all.
	<li>A fourth <var>AddElement</var> invocation adds an element (to the first). The function arguments specify a non-prefixed name and also a <var class="term">URI</var> value. This new URI is the added element's default namespace.		<li>A fourth <var>AddElement</var> invocation adds an element (to the first). The function arguments specify a non-prefixed name and also a <var class="term">URI</var> value. This new URI is the added element's default namespace.
	<li>A fifth <var>AddElement</var> invocation adds an element to the element added by the previous <var>AddElement</var>. The function arguments include no name prefix and no <var class="term">URI</var> value,		<li>A fifth <var>AddElement</var> invocation adds an element to the element added by the previous <var>AddElement</var>. The function arguments include no name prefix and no <var class="term">URI</var> value,
Line 174:		Line 174:
	<li><var class="term">Name</var> prefixed and Namespace On, but <var class="term">URI</var> missing and no declaration for prefix in scope.		<li><var class="term">Name</var> prefixed and Namespace On, but <var class="term">URI</var> missing and no declaration for prefix in scope.
	<li><var class="term">Value</var> violates the rules for an XML element value (that is, it contains an invalid character).		<li><var class="term">Value</var> violates the rules for an XML element value (that is, it contains an invalid character).
	Note that as of <var class="product">[[Sirius Mods\|"Sirius Mods"]]</var> Version 7.6, this check can no longer be bypassed using the <var>[[InvalidChar_(XmlDoc_property)\|InvalidChar]]</var> method — see [[InvalidChar (XmlDoc property)#Usage notes\|"Usage notes for the InvalidChar property"]].		Note that as of <var class="product">[[Sirius Mods\|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"]].
	<li><var class="term">URI</var> is invalid.		<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">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.