The PBDOM_CDATA class represents an XML DOM CDATA section. The PBDOM_CDATA class is derived from PBDOM_TEXT, which inherits from the PBDOM_CHARACTERDATA class.
A PBDOM_CDATA object is used to hold text that contains characters that are prohibited in text objects, such as “<” and “&”, without using entity references. For example, consider the following PBDOM_CDATA object:
<some_text> <![CDATA[ (x < y) & (y < z) => x < z ]]> </some_text>
A PBDOM_TEXT object with the same text content must be written like this:
<some_text> (x < y) & (y < z) => x < z </some_text>
However, although the PBDOM_CDATA class is derived from PBDOM_TEXT, a PBDOM_CDATA object cannot always be inserted in the same context as a PBDOM_TEXT. For example, a PBDOM_TEXT object can be added as a child of a PBDOM_ATTRIBUTE, but a PBDOM_CDATA object cannot.
Some of the inherited methods from PBDOM_OBJECT serve no meaningful objective, and only default or trivial functionalities result. These are described in the following table:
Method |
Always returns |
|---|---|
AddContent |
current PBDOM_CDATA |
GetContent |
false |
GetName |
a string "#cdata" |
HasChildren |
false |
InsertContent |
current PBDOM_CDATA |
IsAncestorObjectOf |
false |
RemoveContent |
false |
SetContent |
current PBDOM_CDATA |
SetName |
false |
PBDOM_CDATA has the following non-trivial methods:
Appends the input string or the input text data of the PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_CDATA object.
pbdom_cdata_name.Append(string strAppend)
pbdom_cdata_name.Append(pbdom_characterdata pbdom_characterdata_ref)
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
strAppend |
The string you want appended to the existing text of the current PBDOM_CDATA object |
pbdom_characterdata_ref |
The referenced PBDOM_CHARACTERDATA object whose text data is to be appended to the existing text of the current PBDOM_CDATA object |
PBDOM_CHARACTERDATA.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA (applies to second syntax).
Creates and returns a clone of the current PBDOM_CDATA.
pbdom_cdata_name.Clone(boolean bDeep)
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA. |
bDeep |
A boolean specifying whether a deep or shallow clone is returned. Values are true for a deep clone and false for a shallow clone. This argument is currently ignored. |
PBDOM_OBJECT. The return value is a clone of the current PBDOM_CDATA housed in a PBDOM_OBJECT.
This example tests the following characteristics of a cloned PBDOM_CDATA object:
The contents of an original and cloned PBDOM_CDATA object are exactly the same
A cloned PBDOM_CDATA initially has no parent object
A cloned PBDOM_CDATA is initially contained within the same owner document as the original
PBDOM_BUILDER pbdom_buildr
PBDOM_DOCUMENT pbdom_doc
PBDOM_CDATA pbdom_cdat
PBDOM_OBJECT pbdom_obj_array[]
string strXML = "<!DOCTYPE root [<!ELEMENT root (#PCDATA)>]><root><![CDATA[This is a CDATA Section.]]></root>"
try
// Build a PBDOM_DOCUMENT based on strXML.
pbdom_buildr = Create PBDOM_BUILDER
pbdom_doc = pbdom_buildr.BuildFromString (strXML)
// Get the contents of the root element.
pbdom_doc.GetRootElement().GetContent(pbdom_obj_array)
// Test if the root element contains only one child object.
if (UpperBound(pbdom_obj_array) = 1) then
MessageBox ("Pass", "Root Element has only one child.")
else
MessageBox ("Fail", "Root Element must have only one child.")
end if
// Make a clone of the only child of the root element.
pbdom_cdat = pbdom_obj_array[1].Clone(true)
// Test if the clone is a PBDOM_CDATA object.
if (pbdom_cdat.GetObjectClassString() = "pbdom_cdata") then
MessageBox ("Pass", &
"The first child, after being cloned, is indeed a PBDOM_CDATA object.")
else
MessageBox ("Fail", "The first child, after being cloned, " &
+ "is found to be a " + pbdom_cdat.GetObjectClassString() + " object.")
end if
// Test if the clone is a CDATA section.
if (pbdom_cdat.GetText() = "This is a CDATA Section.") then
MessageBox ("Pass", "The text contents of the clone is correct.")
else
MessageBox ("Fail", "The text contents of the clone is : [" &
+ pbdom_cdat.GetText() + "]. This is incorrect.")
end if
// Test that the clone has no parent.
if (Not IsValid(pbdom_cdat.GetParentObject())) then
MessageBox ("Pass", "The clone has no parent.")
else
MessageBox ("Fail", "The clone should have no parent.")
end if
// Test that the clone's owner document is the same
// as the original's owner document.
if (pbdom_cdat.GetOwnerDocumentObject() = pbdom_doc) then
MessageBox ("Pass", "The clone's owner document is correct.")
else
MessageBox ("Fail", "The clone's owner document is incorrect.")
end if
catch (PBDOM_EXCEPTION pbdom_except)
MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())
end try
The Clone method creates a new PBDOM_CDATA object that is a duplicate of, and a separate object from, the original. The clone of a PBDOM_CDATA is always identical to its original whether deep or shallow cloning is invoked, because a PBDOM_CDATA object does not contain any subtree of child PBDOM_OBJECTs.A PBDOM_CDATA clone has no parent. However, the clone resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_CDATA is standalone, the clone is standalone.
Detaches a PBDOM_CDATA from its parent PBDOM_OBJECT.
pbdom_cdata_name.Detach()
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
PBDOM_OBJECT. The current PBDOM_CDATA detached from its parent.
If the current PBDOM_CDATA object has no parent, no modifications occur.
Tests for the equality of the current PBDOM_CDATA and a referenced PBDOM_OBJECT.
pbdom_cdata_name.Equals(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
pbdom_object_ref |
A PBDOM_OBJECT to test for equality with the current PBDOM_CDATA |
Boolean. Returns true if the current PBDOM_CDATA object is equivalent to the referenced PBDOM_OBJECT and false otherwise.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
True is returned only if the referenced PBDOM_OBJECT is also a derived PBDOM_CDATA object and refers to the same DOM object as the current PBDOM_CDATA. Two separately created PBDOM_CDATA objects, for example, can contain exactly the same text but not be equal.
Returns a long integer code that indicates the class of the current PBDOM_OBJECT.
pbdom_object_name.GetObjectClass()
Argument |
Description |
|---|---|
pbdom_object_name |
The name of a PBDOM_OBJECT |
Long. GetObjectClass returns a long integer code that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_CDATA object, the returned value is 8.
Returns a string form of the class of the PBDOM_OBJECT.
pbdom_object_name.GetObjectClassString()
Argument |
Description |
|---|---|
pbdom_object_name |
The name of a PBDOM_OBJECT |
String. GetObjectClassString returns a string that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_CDATA object, the returned string is “pbdom_cdata”.
Returns the owning PBDOM_DOCUMENT of the current PBDOM_CDATA.
pbdom_cdata_name.GetOwnerDocumentObject()
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
PBDOM_OBJECT.
If there is no owning PBDOM_DOCUMENT, null is returned.
Returns the parent PBDOM_OBJECT of the PBDOM_CDATA. If there is no parent, null is returned.
pbdom_cdata_name.GetParentObject()
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
PBDOM_OBJECT.
Returns the text data that is contained within the current PBDOM_CDATA object.
pbdom_cdata_name.GetText()
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
String. The textual content of the current PBDOM_CDATA object.
Returns the text data that is contained within the current PBDOM_CDATA object, with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.
pbdom_cdata_name.GetTextNormalize()
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
String.
If no textual value exists for the current PBDOM_OBJECT, or if only whitespace characters exist, an empty string is returned.
Returns the textual content of the current PBDOM_CDATA object with all surrounding whitespace characters removed.
pbdom_cdata_name.GetTextTrim()
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
String.
If no textual value exists for the current PBDOM_CDATA, or if only whitespace characters exist, an empty string is returned.
Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_CDATA.
pbdom_cdata_name.SetParentObject(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
pbdom_object_ref |
A PBDOM_OBJECT to be set as the parent of this PBDOM_CDATA object |
PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – If the current PBDOM_CDATA already has a parent.
EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT – If the input PBDOM_OBJECT is of a class that does not have a legal parent-child relationship with the PBDOM_CDATA class.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – If the input PBDOM_OBJECT requires a user-defined name and it has not been named.
The PBDOM_OBJECT that you set to be the parent of the current PBDOM_CDATA must have a legal parent-child relationship. If it does not, an exception is thrown. Only a PBDOM_ELEMENT object can be set as the parent of a PBDOM_CDATA object.
Sets the input string to be the text content of the current PBDOM_CDATA object.
pbdom_cdata_name.SetText(string strSet)
Argument |
Description |
|---|---|
pbdom_cdata_name |
The name of a PBDOM_CDATA |
strSet |
The string you want set as the text of the PBDOM_CDATA |
PBDOM_CHARACTERDATA. This PBDOM_CDATA modified and returned as a PBDOM_CHARACTERDATA object.
