AllowXmlElement (XmlDoc property): Difference between revisions
m (fix "using boolean enumerations" link) |
mNo edit summary |
||
| (8 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:XmlDoc:AllowXmlElement subtitle}} | {{Template:XmlDoc:AllowXmlElement subtitle}} | ||
The <var>AllowXmlElement </var> property indicates whether or not the method object <var>XmlDoc</var> allows the deserialization of an XML document that contains | The <var>AllowXmlElement </var> property indicates whether or not the method object <var>XmlDoc</var> allows the deserialization of an XML document that contains [[XmlDoc API#XmlDoc node types|Element nodes]] that begin with the character sequence <code>xml</code> (regardless of case). | ||
A <var>[[Boolean]]</var> value of <var>True</var> allows such deserializations. The default value, < | A <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> value of <var>True</var> allows such deserializations. The default value, <var>False</var>, cancels the request if such a deserialization is attempted. | ||
==Syntax== | ==Syntax== | ||
{{Template:XmlDoc:AllowXmlElement syntax}} | {{Template:XmlDoc:AllowXmlElement syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%currentBoolean</th> | <tr><th>%currentBoolean</th> | ||
<td>The <var>Boolean</var> enumeration value of <var class="term">doc</var>'s <var>AllowXmlElement</var> property | <td>The <var>Boolean</var> enumeration value of <var class="term">doc</var>'s <var>AllowXmlElement</var> property. </td></tr> | ||
<tr><th>doc</th> | <tr><th>doc</th> | ||
<td>An <var>XmlDoc</var> object expression.</td></tr> | <td>An <var>XmlDoc</var> object expression.</td></tr> | ||
<tr><th>newBoolean</th> | <tr><th>newBoolean</th> | ||
<td>The <var>Boolean</var> value to assign to <var class="term">doc</var>'s <var>AllowXmlElement</var> property.</td></tr> | <td>The <var>Boolean</var> value to assign to <var class="term">doc</var>'s <var>AllowXmlElement</var> property.</td></tr> | ||
| Line 24: | Line 27: | ||
Therefore, you should use care with element names: using an element name such as <code>XML</code> makes you vulnerable to a change in the standards that would leave your document incompatible with them. | Therefore, you should use care with element names: using an element name such as <code>XML</code> makes you vulnerable to a change in the standards that would leave your document incompatible with them. | ||
'''Note:''' This property does not allow the <var>[[AddElement_(XmlDoc/XmlNode_function)|AddElement]]</var> method to add an element with a name that starts with "xml". However, as shown in the [[#Adding an element to a document| | <p class="note">'''Note:''' This property does not allow the <var>[[AddElement_(XmlDoc/XmlNode_function)|AddElement]]</var> method to add an element with a name that starts with "xml". However, as shown in the [[#Adding an element to a document|Adding an element to a document]] example below, it is easy to use the <var>[[LoadXml_(XmlDoc/XmlNode_function)|LoadXml]]</var> method to accomplish this. </p> | ||
</ul> | </ul> | ||
| Line 33: | Line 35: | ||
<p class="code">%str = %doc:AllowXmlElement:ToString | <p class="code">%str = %doc:AllowXmlElement:ToString | ||
</p> | </p> | ||
Taking advantage of the implicit- | Taking advantage of the [[Enumerations#Usage Notes|implicit-ToString]] feature, you can print this value directly by using this: | ||
<p class="code">print %doc:AllowXmlElement | <p class="code">print %doc:AllowXmlElement | ||
</p> | </p> | ||
===Deserializing an entire XML document=== | ===Deserializing an entire XML document=== | ||
The following request: | The following request: | ||
| Line 48: | Line 51: | ||
<p class="output">%d:allowXmlElement is True | <p class="output">%d:allowXmlElement is True | ||
</p> | </p> | ||
===Adding an element to a document=== | ===Adding an element to a document=== | ||
The following request: | The following request: | ||
| Line 67: | Line 69: | ||
</nowiki></p> | </nowiki></p> | ||
==Request- | ==Request-cancellation errors (for set method)== | ||
This list is not exhaustive: it does <i>not</i> include all the errors that are request cancelling. | |||
<ul> | <ul> | ||
<li><var class="term">newBoolean</var> is an invalid value ( | <li>The <var class="term">newBoolean</var> argument is an invalid value (that is, not a <var>Boolean</var> value). | ||
</ul> | </ul> | ||
==See also== | ==See also== | ||
{{Template:XmlDoc:AllowXmlElement footer}} | {{Template:XmlDoc:AllowXmlElement footer}} | ||
Latest revision as of 17:20, 3 March 2014
May Element names begin with "xml"? (XmlDoc class)
The AllowXmlElement property indicates whether or not the method object XmlDoc allows the deserialization of an XML document that contains Element nodes that begin with the character sequence xml (regardless of case).
A Boolean value of True allows such deserializations. The default value, False, cancels the request if such a deserialization is attempted.
Syntax
%currentBoolean = doc:AllowXmlElement doc:AllowXmlElement = newBoolean
Syntax terms
| %currentBoolean | The Boolean enumeration value of doc's AllowXmlElement property. |
|---|---|
| doc | An XmlDoc object expression. |
| newBoolean | The Boolean value to assign to doc's AllowXmlElement property. |
Usage notes
- Deserializing Elements whose name begins with "xml" was restricted due to the following excerpt from the XML standard:
- Names beginning with the string "xml", or any string which would match (('X'|'x') ('M'|'m') ('L'|'l')), are reserved for standardization in this or future versions of this specification.
Therefore, you should use care with element names: using an element name such as
XMLmakes you vulnerable to a change in the standards that would leave your document incompatible with them.Note: This property does not allow the AddElement method to add an element with a name that starts with "xml". However, as shown in the Adding an element to a document example below, it is easy to use the LoadXml method to accomplish this.
Examples
Displaying the property
The following example obtains the string value of the AllowXmlElement property:
%str = %doc:AllowXmlElement:ToString
Taking advantage of the implicit-ToString feature, you can print this value directly by using this:
print %doc:AllowXmlElement
Deserializing an entire XML document
The following request:
begin %d object xmlDoc auto new %d:AllowXmlElement = true %d:loadXml('<t>Test<xmlnode></xmlnode></t>') printText{~} is {%d:allowXmlElement} end
prints
%d:allowXmlElement is True
Adding an element to a document
The following request:
begin %d object xmlDoc auto new %n object xmlNode %n = %d:addElement('xyz') %d:allowXmlElement = true %n:LoadXml('<xmlElt/>') %d:print end
prints
<xyz> <xmlElt/> </xyz>
Request-cancellation errors (for set method)
This list is not exhaustive: it does not include all the errors that are request cancelling.
- The newBoolean argument is an invalid value (that is, not a Boolean value).