AddTopElement (XmlDoc function): Difference between revisions
m (remove spurious underscores in see also) |
m (→Syntax terms) |
||
Line 13: | Line 13: | ||
<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. | ||
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 | 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: |
Revision as of 20:47, 22 May 2011
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:
|
MoveNamespace | This optional, but 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 |
Usage notes
- If a URI argument is specified, the XmlDoc's Namespace property 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></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 theMoveNamespace=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></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
- name violates the rules for an XML element name.
- name is prefixed, but the XmlDoc Namespace property is
None
. - name is prefixed and Namespace is
On
, but URI is missing. - 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
- For more information about namespace declarations, see "Names and namespaces".
- For more information about URIs, see "Uniform Resource Identifier syntax".
- AddElement and InsertElementBefore also add an Element node. AddElement adds an Element as the last child of the node pointed to by the method object; InsertElementBefore adds an Element as the immediately preceding sibling of the node pointed to by the method object.
- These methods are useful for working with namespaces: