The PBDOM_CHARACTERDATA class represents character-based content (not markup) within an XML document. It extends the PBDOM_OBJECT class with a set of methods specifically intended for manipulating character data in the DOM.
The PBDOM_CHARACTERDATA class is the parent class of three other PBDOM classes:
PBDOM_TEXT
PBDOM_CDATA
PBDOM_COMMENT
The PBDOM_CHARACTERDATA class, like its parent class PBDOM_OBJECT, is a “virtual” class (similar to a virtual C++ class) in that it is not expected to be directly instantiated and used.
For example, in the following code, the attempt to set the text of pbdom_chrdata raises an exception:
PBDOM_CHARACTERDATA pbdom_chrdata
pbdom_chrdata = CREATE PBDOM_CHARACTERDATA
pbdom_chrdata.SetText ("character string")//error
In this example, the attempt to set the text of pbdom_chrdata succeeds because pbdom_chrdata is declared as a PBDOM_CHARACTERDATA but instantiated as a PBDOM_TEXT:
PBDOM_CHARACTERDATA pbdom_chrdata
pbdom_chrdata = CREATE PBDOM_TEXT
pbdom_chrdata.SetText ("character string")//success
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_CHARACTERDATA |
GetContent |
false |
InsertContent |
current PBDOM_CHARACTERDATA |
RemoveContent |
false |
SetContent |
current PBDOM_CHARACTERDATA |
SetName |
false |
PBDOM_CHARACTERDATA has the following non-trivial methods:
The Append method is overloaded:
Syntax 1 appends an input string to the text content that already exists within the current PBDOM_CHARACTERDATA object.
Syntax 2 appends the text data of a PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_CHARACTERDATA object.
For this syntax |
See |
|---|---|
Append(string strAppend) |
|
Append(pbdom_characterdata pbdom_characterdata_ref) |
Appends an input string to the text content that already exists within the current PBDOM_CHARACTERDATA object.
pbdom_text_name.Append(string strAppend)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_CHARACTERDATA object |
strAppend |
The string you want appended to the existing text of the current PBDOM_CHARACTERDATA object |
PBDOM_CHARACTERDATA. The current PBDOM_CHARACTERDATA modified and returned as a PBDOM_CHARACTERDATA object.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA object is not a reference to an object derived from PBDOM_CHARACTERDATA.
In this example, the PowerScript code builds a PBDOM_DOCUMENT based on the following DOM Tree:
<abc> <data> <child_1> My Text </child_1> <child_2> <!--My Comment--> </child_2> <child_3> <![CDATA[My CDATA]]> </child_3> </data> </abc>
The root element abc has a child element, data, that has three child elements. child_1 contains a child PBDOM_TEXT with the string “My Text”. child_2 contains a child PBDOM_COMMENT with the string “My Comment”. child_3 contains a child PBDOM_CDATA with the string “My CDATA”.
In the following PowerScript code, the single statement that
follows the comment // obtain
the child PBDOM_TEXT of child_1 does
the following:
Obtains the root element of the PBDOM_DOCUMENT pbdom_doc using GetRootElement. A new PBDOM_ELEMENT representing the root element abc is created in memory and returned.
Calls the GetChildElement method on the returned root abc PBDOM_ELEMENT using data as the parameter to single out the data child element. A PBDOM_ELEMENT representing the data element is created in memory and returned.
Calls the GetChildElement on the returned data PBDOM_ELEMENT, using child_1 as the parameter to single out the child_1 child element. A PBDOM_ELEMENT representing the child_1 element is created in memory and returned.
Calls the GetContent method on the returned child_1 PBDOM_ELEMENT, supplying a reference to the unbounded array pbdom_chardata_array.
You can supply PBDOM_CHARACTERDATA array instead of a PBDOM_OBJECT array because PBDOM_CHARACTERDATA is a subclass of PBDOM_OBJECT. However, GetContent fails if child_1 contains any objects other than PBDOM_CHARACTERDATA objects.
Because child_1 holds only the PBDOM_TEXT containing the string “My Text”, this statement returns an array that has only one array item. The next statement appends another string to the array item. The example then repeats these steps for child_2 and child_3 and saves pbdom_doc to a file:
PBDOM_Builder pbdombuilder_new pbdom_document pbdom_doc PBDOM_CHARACTERDATA pbdom_chardata_array[] string strXML = "<abc><data><child_1>My Text</child_1><child_2><!--My Comment--></child_2><child_3><![CDATA[My CDATA]]></child_3></data></abc>" TRY pbdombuilder_new = Create PBDOM_Builder pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
// obtain the child PBDOM_TEXT of child_1
pbdom_doc.GetRootElement().GetChildElement("data").&
GetChildElement("child_1"). &
GetContent(pbdom_chardata_array)
// append the string "Now Appended" to the text
// returned by the call to GetContent
pbdom_chardata_array[1].Append (" Now Appended")
// repeat for child_2 and child_3
pbdom_doc.GetRootElement().GetChildElement("data").&
GetChildElement("child_2"). &
GetContent(pbdom_chardata_array)
pbdom_chardata_array[1].Append (" Now Appended")
pbdom_doc.GetRootElement().GetChildElement("data").&
GetChildElement("child_3"). &
GetContent(pbdom_chardata_array)
pbdom_chardata_array[1].Append (" Now Appended")
// save pbdom_doc to a file
pbdom_doc.SaveDocument ("c:\pbdom_doc_1.xml")
Destroy pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
The saved file contains the following:
<abc> <data> <child_1> My Text Now Appended </child_1> <child_2> <!--My Comment Now Appended--> </child_2> <child_3> <![CDATA[My CDATA Now Appended]]> </child_3> </data> </abc>
Appends the text data of a PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_CHARACTERDATA object.
pbdom_text_name.Append(pbdom_characterdata pbdom_characterdata_ref)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_CHARACTERDATA |
pbdom_characterdata_ref |
The referenced PBDOM_CHARACTERDATA object whose text data is to be appended to the existing text of the current PBDOM_CHARACTERDATA object |
PBDOM_CHARACTERDATA. The current PBDOM_CHARACTERDATA modified and returned as a PBDOM_CHARACTERDATA object.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the current PBDOM_CHARACTERDATA or the input PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Note that JDOM does not define an Append method for its CHARACTERDATA class. Because PBDOM implements its Append method in the base PBDOM_CHARACTERDATA class, a PBDOM_TEXT object, a PBDOM_CDATA object, and a PBDOM_TEXT object can append their internal text data to each other because they are all PBDOM_CHARACTERDATA-derived objects.
Creates and returns a clone of the current PBDOM_CHARACTERDATA.
pbdom_chardata_name.Clone(boolean bDeep)
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA. |
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.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
This example creates a PBDOM_DOCUMENT based on the following DOM tree:
<abc> <data>Data</data> </abc>
The PowerScript code obtains the data element of the root element as a PBDM_ELEMENT and obtains an array of its children. The array has only one item, the PBDOM_TEXT containing the string “data”:
PBDOM_BUILDER pbdombuilder_new
PBDOM_DOCUMENT pbdom_doc
PBDOM_ELEMENT pbdom_elem
PBDOM_CHARACTERDATA pbdom_chardata_1
PBDOM_CHARACTERDATA pbdom_chardata_2
PBDOM_CHARACTERDATA pbdom_chardata_3
PBDOM_OBJECT pbdom_obj_array[]
string strXML = "<abc><data>Data</data></abc>"
TRY
pbdombuilder_new = CREATE PBDOM_BUILDER
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
// get the data element, store in pbdom_elem,
// and get an array of its children
pbdom_elem = pbdom_doc.GetRootElement(). &
GetChildElement("data")
pbdom_elem.GetContent(pbdom_obj_array)
This PBDOM_TEXT is assigned into a PBDOM_CHARACTERDATA object, pbdom_chardata_1.
Calling GetObjectClassString on pbdom_chardata_1 returns
the class name of the actual object contained within it, pbdom_text. Calling GetText on
it returns the string Data:
pbdom_chardata_1 = pbdom_obj_array[1]
MessageBox ("Class", &
pbdom_chardata_1.GetObjectClassString())
MessageBox ("Text", pbdom_chardata_1.GetText())
Calling Clone on pbdom_chardata_1 creates a new PBDOM_CHARACTERDATA object. However, because the actual object referenced by pbdom_chardata_1 is a PBDOM_TEXT, the clone is a PBDOM_TEXT object.Calling GetObjectClassString and GetText on the clone have the same result as for pbdom_chardata_1. The clone and the original object are separate objects and a call to Equals returns false:
pbdom_chardata_2 = pbdom_chardata_1.Clone(TRUE)
MessageBox ("Class", &
pbdom_chardata_2.GetObjectClassString())
MessageBox ("Text", pbdom_chardata_2.GetText())
if (pbdom_chardata_1.Equals(pbdom_chardata_2)) then
MessageBox ("Equals", &
"pbdom_chardata_1 equals pbdom_chardata_2")
else
MessageBox ("Equals", &
"pbdom_chardata_1 NOT equals pbdom_chardata_2")
end if
However, a call to Equals returns true if the object being compared to pbdom_chardata_1 is a reference to pbdom_chardata_1:
pbdom_chardata_3 = pbdom_chardata_1
if (pbdom_chardata_1.Equals(pbdom_chardata_3)) then
MessageBox ("Equals", &
"pbdom_chardata_1 equals pbdom_chardata_3")
else
MessageBox ("Equals", &
"pbdom_chardata_1 NOT equals pbdom_chardata_3")
end if
DESTROY pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
The Clone method creates a new PBDOM_CHARACTERDATA object which is a duplicate of, and a separate object from, the original. Calling Equals using these two objects returns false.
The clone of a PBDOM_CHARACTERDATA object is always identical to its original whether bDeep is true or false, because a PBDOM_CHARACTERDATA object contains no subtree of child PBDOM_OBJECTs.A PBDOM_CHARACTERDATA clone has no parent, but it resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_CHARACTERDATA is standalone, the clone is standalone.
Detaches a PBDOM_CHARACTERDATA object from its parent.
pbdom_chardata_name.Detach()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA object |
PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
This example creates a PBDOM_DOCUMENT based on the following DOM tree:
<abc> <data>Data</data> </abc>
The PowerScript code obtains the root element, uses it to obtain the child element, and then obtains an array of the child element’s own children. This array has a single item, the PBDOM_TEXT object with the text Data. The array can be cast to a PBDOM_CHARACTERDATA object because it does not contain any objects that are not derived from PBDOM_CHARACTERDATA.
Calling Detach separates the PBDOM_TEXT object from its parent PBDOM_OBJECT, data.
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_document pbdom_owner_doc
PBDOM_CHARACTERDATA pbdom_chardata
PBDOM_OBJECT pbdom_obj_array[]
string strXML = "<abc><data>Data</data></abc>"
TRY
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_doc.GetRootElement(). &
GetChildElement("data"). &
GetContent(pbdom_obj_array)
pbdom_chardata = pbdom_obj_array[1]
pbdom_chardata.Detach()
pbdom_doc.SaveDocument("c:\pbdom_doc_1.xml")
Destroy pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
When the document is saved to a file, the file’s contents are as follows, because the PBDOM_TEXT object was removed from data:
<abc> <data/> </abc>
Nothing occurs if the PBDOM_CHARACTERDATA object has no parent.
Tests for the equality of the current PBDOM_CHARACTERDATA and a referenced PBDOM_OBJECT.
pbdom_chardata_name.Equals(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA object |
pbdom_object_ref |
A reference to a PBDOM_OBJECT to test for equality with the current PBDOM_CHARACTERDATA object |
Boolean. Returns true if the current PBDOM_CHARACTERDATA is equivalent to the input PBDOM_OBJECT and false otherwise.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
True is returned only if the referenced PBDOM_OBJECT is also a derived PBDOM_CHARACTERDATA object and refers to the same DOM object as the current PBDOM_CHARACTERDATA. Two separately created PBDOM_COMMENTs, for example, can contain exactly the same text but are not equal.
The GetOwnerDocumentObject method returns the owning PBDOM_DOCUMENT of the current PBDOM_CHARACTERDATA.
pbdom_chardata_name.GetOwnerDocumentObject()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA object |
PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not associated with a derived PBDOM_CHARACTERDATA class.
This example creates a PBDOM_DOCUMENT based on the following DOM tree:
<abc> <data>Data</data> </abc>
The PowerScript code obtains the root element, uses it to obtain the child element, and then obtains an array of the child element’s own children. This array has a single item, the PBDOM_TEXT object with the text Data. The array can be cast to a PBDOM_CHARACTERDATA object because it does not contain any objects that are not derived from PBDOM_CHARACTERDATA,
The call to GetOwnerDocumentObject returns a PBDOM_OBJECT, which is stored in a PBDOM_DOCUMENT called pbdom_owner_doc. The call to Equals tests whether the owner document of the “Data” PBDOM_TEXT and the main document, referenced using pbdom_doc, refer to the same document.
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_document pbdom_owner_doc
pbdom_element pbdom_elem
PBDOM_CHARACTERDATA pbdom_chardata
PBDOM_OBJECT pbdom_obj_array[]
string strXML = "<abc><data>Data</data></abc>"
TRY
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_elem = pbdom_doc.GetRootElement(). &
GetChildElement("data")
pbdom_elem.GetContent(pbdom_obj_array)
pbdom_chardata = pbdom_obj_array[1]
pbdom_owner_doc = &
pbdom_chardata.GetOwnerDocumentObject()
if (pbdom_doc.Equals(pbdom_owner_doc)) then
MessageBox ("Equals", &
"pbdom_doc Equals pbdom_owner_doc")
else
MessageBox ("Equals", &
"pbdom_doc Not Equals pbdom_owner_doc")
end if
Destroy pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
This example creates a PBDOM_DOCUMENT based on the same DOM tree as example 1. It creates a PBDOM_TEXT, stores it in the PBDOM_CHARACTERDATA variable pbdom_chardata, and assigns it some text. Objects created in this way are standalone objects—they have no owner document or parent. Calling GetOwnerDocumentObject on pbdom_chardata returns null.
The code then adds pbdom_chardata as a child to the data element. This implicitly imports pbdom_chardata into the original document. pbdom_chardata now has an owner document and a parent (the data element). Calling GetOwnerDocumentObject on pbdom_chardata returns the original document. When the returned PBDOM_DOCUMENT has been assigned into pbdom_owner_doc, a call to Equals to compare pbdom_doc with pbdom_owner_doc returns true:
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_document pbdom_owner_doc
PBDOM_CHARACTERDATA pbdom_chardata
string strXML = "<abc><data>Data</data></abc>"
TRY
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_chardata = Create PBDOM_TEXT
pbdom_chardata.SetText(" Some Text")
if (IsValid (pbdom_chardata.GetOwnerDocumentObject())) then
MessageBox ("Owner Document", &
"PBDOM_TEXT (~'Some Text~') has an owner document.")
else
MessageBox ("Owner Document", &
"PBDOM_TEXT (~'Some Text~') has NO owner document.")
end if
pbdom_doc.GetRootElement().GetChildElement("data"). &
AddContent(pbdom_chardata)
pbdom_owner_doc = pbdom_chardata.GetOwnerDocumentObject()
if (pbdom_doc.Equals(pbdom_owner_doc)) then
MessageBox ("Equals", "pbdom_doc Equals pbdom_owner_doc")
else
MessageBox ("Equals", "pbdom_doc Not Equals pbdom_owner_doc")
end if
Destroy pbdombuilder_new
Destroy pbdom_chardata
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
If there is no owning PBDOM_DOCUMENT, null is returned.
The GetName method allows you to obtain the name of the current PBDOM_CHARACTERDATA.
pbdom_chardata_name.GetName()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA object |
String.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
The returned string depends on the specific type of DOM object that is contained within PBDOM_CHARACTERDATA.
Note
A PBDOM_CHARACTERDATA is abstract and is not to be
instantiated into an object of its own. Thus, there is no name returned
as “#characterdata”.
The following table lists the return values based on the type of DOM Object contained within PBDOM_CHARACTERDATA.
DOM Object |
Return Value |
|---|---|
PBDOM_CDATA |
"#cdata-section" |
PBDOM_COMMENT |
"#comment" |
PBDOM_TEXT |
"#text" |
The GetObjectClass method 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 value that indicates the class of the current PBDOM_OBJECT.
The possible return values for classes inherited from PBDOM_CHARACTERDATA are:
7 for PBDOM_TEXT
8 for PBDOM_CDATA
9 for PBDOM_COMMENT
The PBDOM_CHARACTERDATA class itself cannot be instantiated, so the class ID 6, for PBDOM_CHARACTERDATA, is never returned.
The GetObjectClassString method 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.
The possible return values for classes inherited from PBDOM_CHARACTERDATA are:
pbdom_text
pbdom_cdata
pbdom_comment
The PBDOM_CHARACTERDATA class itself cannot be instantiated, so the string “pbdom_characterdata” is never returned.
This example creates a PBDOM_DOCUMENT based on the following DOM tree:
<abc> <data> Data with a < character <!-- Comment with a < character --> <![CDATA[ CDATA with an actual > character and an entity reference < ]]> </data> </abc>
The PowerScript code obtains the root element, uses it to obtain the child element, and then obtains an array of the child element’s own children. This is an array of three PBDOM_OBJECTs, each of which is a child node of data. This array provides the ability to access and manipulate the child nodes, but to illustrate the virtual nature of the PBDOM_CHARACTERDATA class and the calling of methods of the PBDOM_CHARACTERDATA class, the example defines an array of PBDOM_CHARACTERDATA objects.
Each array item of the pbdom_obj_array is assigned to the pbdom_chardata array, so you can call the methods of each array item without needing to know what subclass the item belongs to.
Children must be subclasses of PBDOM_CHARACTERDATA
If the data element contained a child
that was not a subclass of PBDOM_CHARACTERDATA, the FOR loop
to assign each pbdom_obj_array item
to a corresponding pbdom_chardata array
item would fail when it reached that item.
The MessageBox calls illustrate how the entity reference < is
handled by the different PBDOM_CHARACTERDATA subclasses.
In the PBDOM_TEXT object, it is expanded. In the PBDOM_COMMENT
and PBDOM_CDATA objects, it is not. The character to which
the entity reference refers, “>”, can also be
included in a PBDOM_CDATA object.
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_element pbdom_elem
PBDOM_CHARACTERDATA pbdom_chardata[]
PBDOM_OBJECT pbdom_obj_array[]
long l = 0
string strXML = "<abc><data>Data with a < character<!-- Comment with a < character --><![CDATA[ CDATA with an actual > character and an entity reference < ]]></data></abc>"
TRY
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_elem = pbdom_doc.GetRootElement(). &
GetChildElement("data")
pbdom_elem.GetContent(pbdom_obj_array)
// populate an array of PBDOM_CHARACTERDATA objects
for l = 1 to UpperBound(pbdom_obj_array)
pbdom_chardata[l] = pbdom_obj_array[l]
next
for l = 1 to UpperBound(pbdom_chardata)
MessageBox ("Class", &
pbdom_chardata[l].GetObjectClassString())
MessageBox ("Text", pbdom_chardata[l].GetText())
next
Destroy pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
The GetParentObject method returns the parent PBDOM_OBJECT of the current PBDOM_CHARACTERDATA.
pbdom_chardata_name.GetParentObject()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA object |
PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
This example creates a PBDOM_DOCUMENT based on the following DOM tree and demonstrates how a PBDOM_CHARACTERDATA INSTANCE can be detached from its parent:
<abc> <data>Data</data> </abc>
The PowerScript code obtains the root element, uses it to obtain the child element, and then obtains an array of the child element’s own children. This array has a single item, the PBDOM_TEXT object with the text Data. The array can be cast to a PBDOM_CHARACTERDATA object, because it does not contain any objects that are not derived from PBDOM_CHARACTERDATA.
The parent of pbdom_chardata_1 is the data element. The following steps detach it from its parent:
Create a PBDOM_COMMENT in the PBDOM_CHARACTERDATA object pbdom_chardata_2 and assign to it the text “Some Comments”.
Set pbdom_chardata_2 as an array item of pbdom_obj_array.
Call SetContent on the parent of pbdom_chardata_1 (the data element).
Calling SetContent resets the contents of data, which can cause its original contents (including pbdom_chardata_1) to be removed, depending on what is stored inside pbdom_obj_array. Because pbdom_obj_array contains only the newly created PBDOM_COMMENT, pbdom_chardata_2, data will have only this PBDOM_COMMENT as its child.
pbdom_chardata_1 will have no parent, because it has been silently detached from it. Calling GetParentObject on it will return null:
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_document pbdom_owner_doc
PBDOM_CHARACTERDATA pbdom_chardata_1
PBDOM_CHARACTERDATA pbdom_chardata_2
PBDOM_OBJECT pbdom_obj_array[]
string strXML = "<abc><data>Data</data></abc>"
TRY
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_doc.GetRootElement(). &
GetChildElement("data"). &
GetContent(pbdom_obj_array)
pbdom_chardata_1 = pbdom_obj_array[1]
pbdom_chardata_2 = Create PBDOM_COMMENT
pbdom_chardata_2.SetText ("Some Comments")
pbdom_obj_array[1] = pbdom_chardata_2
pbdom_chardata_1.GetParentObject(). &
SetContent(pbdom_obj_array)
if (IsValid(pbdom_chardata_1.GetParentObject())) then
MessageBox ("Has Parent Object", &
"PBDOMTEXT (~'Data~') has a parent")
else
MessageBox ("Has Parent Object", &
"PBDOMTEXT (~'Data~') has NO parent")
end if
pbdom_doc.SaveDocument("c:\pbdom_doc_1.xml")
Destroy pbdombuilder_new
Destroy pbdom_chardata_2
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
When the resulting PBDOM_DOCUMENT is saved to a file, it looks like this:
<abc> <data> <!-- Some Comments --> </data> </abc>
The parent is also an object derived from PBDOM_CHARACTERDATA. If the PBDOM_OBJECT has no parent, null is returned.
Calling the GetText method allows you to obtain text data that is contained within the current PBDOM_CHARACTERDATA.
pbdom_chardata_name.GetText()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA object |
String. The text of the current PBDOM_CHARACTERDATA-derived object.
Throws EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
The following table lists the return values based on the type of DOM Object contained within PBDOM_CHARACTERDATA.
DOM Object |
Return Value |
|---|---|
PBDOM_TEXT |
The text data contained within the PBDOM_TEXT object itself. For example, suppose you have the following element: <abc>MY TEXT</abc> If you have a PBDOM_TEXT object to represent the TEXT
NODE “MY TEXT”, then calling GetText on
the PBDOM_TEXT returns the string |
PBDOM_CDATA |
The string data that is contained within the CDATA section itself. For example, suppose you have the following CDATA: <![CDATA[ They’re saying "x < y" & that "z > y" so I guess that means that z > x ]]> If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetText returns the string: They’re saying "x < y" & that "z > y" so I guess that means that z > x |
PBDOM_COMMENT |
The comment itself. For example, suppose you have the following comment: <!--This is a comment. --> Calling GetText on the comment returns the string: This is a comment. |
The GetTextNormalize method allows you to obtain the text data that is contained within the current PBDOM_CHARACTERDATA object, with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.
pbdom_chardata_name.GetTextNormalize()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA object |
String. The following table lists the return values, based on the type of DOM object contained within PBDOM_CHARACTERDATA.
DOM Object |
Return Value |
|---|---|
PBDOM_TEXT |
Suppose you have the following element: <abc> MY TEXT </abc> If there is a PBDOM_TEXT object to represent
the TEXT NODE "MY TEXT", then calling GetTextNormalize on
the PBDOM_TEXT returns the string |
PBDOM_CDATA |
Suppose there is the following CDATA: <![CDATA] They’re saying "x < y" & that "z > y" so I guess that means that z > x ]]> If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetTextNormalize on it returns the string: They’re saying " x < y " & that "z > y" so I guess that means that z > x Note that the initial spaces before “They’re” and the trailing space after the last “x” are removed. Additionally, the spaces between the words “guess” and “that” are reduced to just one space. |
PBDOM_COMMENT |
Suppose there is the following comment: <!--This is a comment --> Calling GetTextNormalize on this comment returns: This is a comment |
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
This example demonstrates:
Using an external general parsed entity.
Using a single line statement to obtain the children PBDOM_OBJECTs of an element.
Obtaining the text of the three separate types of PBDOM_CHARACTERDATA objects : PBDOM_TEXT, PBDOM_COMMENT, and PBDOM_CDATA.
Obtaining the normalized text of the same three separate types of PBDOM_CHARACTERDATA objects.
The difference between the two types of text retrieved in 3 and 4.
Suppose the file C:\entity_text.txt contains the following string:
	 Some External  	 Text 	
The example creates a PBDOM_DOCUMENT pbdom_doc based on the following DOM tree, which is in the file C:\inputfile.txt:
<!DOCTYPE abc [<!ENTITY text1 SYSTEM "c:\entity_text.txt" >]> <abc> <data> &text1; <!-- &text1;--> <![CDATA[&text1;]]> </data> </abc>
The Document Type Declaration defines an external general parsed entity text1.
The example obtains the root element, uses it to obtain the data child element, and then obtains an array of the child element’s own children. PBDOM collects all the PBDOM_OBJECTs that are the children of data and stores them in the PBDOM_OBJECT array pbdom_obj_array.
Next, the FOR loop iterates through all the items in pbdom_obj_array and stores each item in the PBDOM_CHARACTERDATA array pbdom_chardata. This step is not required—the pbdom_obj_array can be used to manipulate the data element’s children. It is done to demonstrate that you can cast each item into a PBDOM_CHARACTERDATA object by assigning it into a PBDOM_CHARACTERDATA array. This is possible if and only if each PBDOM_OBJECT is also derived from PBDOM_CHARACTERDATA. If a PBDOM_OBJECT is not derived from PBDOM_CHARACTERDATA, the PowerBuilder VM throws an exception.
The next FOR loop iterates through all the items of the pbdom_chardata array and calls the GetText and GetTextNormalize methods on each. Each of the returned strings from GetText and GetTextNormalize is delimited by “[“ and “]” characters so that the complete text content displays clearly in the message boxes.
The first child of data is the PBDOM_TEXT &text1;,
which has been declared as an external general parsed entity whose
content is the content of the file c:\entity_text.txt.
The &text1; entity
reference and the entity references it contains are expanded by
the parser. The call to GetTextNormalize strips
away the whitespace characters.
The second child of data is the PBDOM_COMMENT <!--
&text1;--> and the third child is the PBDOM_CDATA <![CDATA[&text1;]]>.
Entity references within comments and CDATA sections are never expanded.
Both GetText and GetTextNormalize return &text1;.
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
PBDOM_CHARACTERDATA pbdom_chardata[]
PBDOM_OBJECT pbdom_obj_array[]
integer iFileNum1
long l = 0
TRY
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromFile &
("C:\inputfile.txt")
pbdom_doc.GetRootElement(). &
GetChildElement("data"). &
GetContent(pbdom_obj_array)
for l = 1 to UpperBound(pbdom_obj_array)
pbdom_chardata[l] = pbdom_obj_array[l]
next
for l = 1 to UpperBound(pbdom_chardata)
MessageBox(pbdom_chardata[l]. &
GetObjectClassString() + "GetText()", &
"[" + pbdom_chardata[l].GetText() + "]")
MessageBox (pbdom_chardata[l]. &
GetObjectClassString() + " GetTextNormalize()", &
"[" + pbdom_chardata[l].GetTextNormalize() + "]")
next
Destroy pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
If no textual value exists for the current PBDOM_OBJECT, or if only whitespace characters exist, an empty string is returned.
The GetTextTrim method returns the textual content of the current PBDOM_CHARACTERDATA object with all surrounding whitespace characters removed.
pbdom_chardata_name.GetTextTrim()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA |
String.
DOM Object |
Return Value |
|---|---|
PBDOM_TEXT |
The text data contained within the PBDOM_TEXT object itself with surrounding whitespace characters removed.For example, suppose there is the following element: <abc> MY TEXT </abc> If there is a PBDOM_TEXT object to represent
the TEXT NODE “MY TEXT”, then calling GetTextTrim on
the PBDOM_TEXT returns the string |
PBDOM_CDATA |
The string data that is contained within the CDATA section itself with surrounding whitespace characters removed. For example, suppose there is the following CDATA: <![CDATA[ They’re saying "x < y" & that "z > y" so I guess that means that z > x ]]> If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetTextTrim on it returns the string: They’re saying " x < y " & that "z > y" so I guess that means that z > x Note that the initial spaces before “They’re” and the trailing space after the last “x” are removed. |
PBDOM_COMMENT |
Suppose there is the following comment: <!-- This is a comment --> Calling GetTextTrim on this comment returns: This is a comment Note that the spaces between the individual words in the comment are preserved. Only the surrounding whitespace characters are removed. |
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
This example demonstrates:
Using an External DTD.
Using a parameter entity.
Using a single line statement to obtain the children PBDOM_OBJECTs of an element.
Obtaining the text of the three separate types of PBDOM_CHARACTERDATA objects : PBDOM_TEXT, PBDOM_COMMENT, and PBDOM_CDATA.
Obtaining the trimmed text of the same three separate types of PBDOM_CHARACTERDATA objects.
The difference between the two types of text retrieved in 4 and 5.
The PowerScript code saves a string into an external file, then creates a PBDOM_DOCUMENT pbdom_doc based on the following DOM tree:
<!DOCTYPE abc SYSTEM "c:\external_entity.dtd"> <abc> <data> &text1; <!-- &text1;--> <![CDATA[&text1;]]> </data> </abc>
c:\external_entity.dtd is an external Document Type Definition file. Its contents are the external subset of the Document Type Definition. The first line declares a PARAMETER entity param_entity_ref that contains the following replacement text:
   PARAMETER ENTITY REFERENCE			
The next line declares a general entity text1 that contains the following replacement text:
%param_entity_ref;
When the entity text1 is used in an XML document, it is expanded to the contents of the PARAMETER entity param_entity_ref.
The PowerScript code then obtains the root element, uses it to obtain the data child element, and then obtains an array of the child element’s own children. PBDOM collects all the PBDOM_OBJECTs that are the children of data and stores them in the PBDOM_OBJECT array pbdom_obj_array.
Next, the FOR loop iterates through all the items in pbdom_obj_array and stores each item in the PBDOM_CHARACTERDATA array pbdom_chardata. This step is not required—the pbdom_obj_array can be used to manipulate the data element’s children. It is done to demonstrate that you can cast each item into a PBDOM_CHARACTERDATA object by assigning it into a PBDOM_CHARACTERDATA array.
This is possible if and only if each PBDOM_OBJECT is also derived from PBDOM_CHARACTERDATA. If a PBDOM_OBJECT is not derived from PBDOM_CHARACTERDATA, the PowerBuilder VM throws an exception.
The next FOR loop iterates through all the items of the pbdom_chardata array and calls the GetText and GetTextTrim methods on each. Each of the returned strings from GetText and GetTextTrim is delimited by “[“ and “]” characters so that the complete text content displays clearly in the message boxes.
The first child of data is the PBDOM_TEXT &text1;,
which expands to the string in param_entity_ref.
The entity references within this string are also expanded and the
Tab and Space characters display when GetText is
called. When GetTextTrim is called, PBDOM removes
the beginning and trailing whitespace characters and the resulting
string is simply PARAMETER ENTITY REFERENCE.The
second child of data is the PBDOM_COMMENT <!--
&text1;-->., and the third child is the
PBDOM_CDATA <![CDATA[&text1;]]>.
The string &text1; is
not considered to be an entity reference by PBDOM because W3C DOM
comments and CDATA sections cannot hold any entity references. Both GetText and GetTextTrim return
the string &text1;.
There are no leading or trailing spaces to remove.
PBDOM_CHARACTERDATA pbdom_chardata[]
PBDOM_OBJECT pbdom_obj_array[]
integer iFileNum1
long l = 0
string strExternalDTD = "<!ENTITY % param_entity_ref ~"   PARAMETER ENTITY REFERENCE			~"><!ENTITY text1 ~"%param_entity_ref;~">"
string strXML = "<!DOCTYPE abc SYSTEM ~"c:\external_entity.dtd~"><abc><data>&text1;<!-- &text1;--><![CDATA[&text1;]]></data></abc>"
TRY
iFileNum1 = FileOpen("c:\external_entity.dtd", &
StreamMode!, Write!, LockWrite!, Replace!)
FileWrite(iFileNum1, strExternalDTD)
FileClose(iFileNum1)
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_doc.GetRootElement(). &
GetChildElement("data"). &
GetContent(pbdom_obj_array)
for l = 1 to UpperBound(pbdom_obj_array)
pbdom_chardata[l] = pbdom_obj_array[l]
next
for l = 1 to UpperBound(pbdom_chardata)
MessageBox (pbdom_chardata[l]. &
GetObjectClassString() + " GetText()", &
"[" + pbdom_chardata[l].GetText() + "]")
MessageBox (pbdom_chardata[l]. &
GetObjectClassString() + " GetTextTrim()" , &
"[" + pbdom_chardata[l].GetTextTrim() + "]")
next
Destroy pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
If no textual value exists for the current PBDOM_CHARACTERDATA, or if only whitespace characters exist, an empty string is returned.
This method returns true if this PBDOM_CHARACTERDATA has at least one child PBDOM_OBJECT. If this PBDOM_CHARACTERDATA has no children, false is returned.
pbdom_chardata_name.HasChildren()
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA. |
Boolean.
Value |
Description |
|---|---|
true |
The current PBDOM_CHARACTERDATA has at least one child PBDOM_OBJECT |
false |
The current PBDOM_CHARACTERDATA has no child PBDOM_OBJECTs |
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
If the PBDOM_CHARACTERDATA has at least one child PBDOM_OBJECT, true is returned. False is returned if there are no children.
Currently, false is always returned because no subclasses of PBDOM_CHARACTERDATA contain child nodes.
The IsAncestorObjectOf method determines whether the current PBDOM_CHARACTERDATA is the ancestor of another PBDOM_OBJECT.
pbdom_chardata_name.IsAncestorObjectOf(pbdom_object pbdom_object_ret)
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA |
pbdom_object_ref |
A PBDOM_OBJECT to check against |
Boolean. Returns true if the current PBDOM_CHARACTERDATA is the ancestor of the referenced PBDOM_OBJECT, and false otherwise.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Currently, false is always returned because no subclasses of PBDOM_CHARACTERDATA contain child nodes. Therefore, they cannot be ancestors of a PBDOM_OBJECT.
The SetParentObject method sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_CHARACTERDATA.
pbdom_chardata_name.SetParentObject(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA |
pbdom_object_ref |
A PBDOM_OBJECT to be set as the parent of this PBDOM_CHARACTERDATA object |
PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA. This exception also occurs 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_CHARACTERDATA already has a parent.
EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT – If the input PBDOM_OBJECT is of a class that does not have a proper parent-child relationship with the class of this PBDOM_CHARACTERDATA.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – If the input PBDOM_OBJECT requires a user-defined name, and it has not been named.
This example creates a PDBOM_DOCUMENT based on the following DOM tree:
<abc> <data> <child_1/> <child_2/> <child_3/> </data> </abc>
The code creates three separate types of PBDOM_CHARACTERDATA objects and stores them in the pbdom_chardata array. It then obtains the root element, uses it to obtain the data child element, and then uses that to obtain the first child element, which it sets as the parent of the first item in the pbdom_chardata array.
The text of the array item is set to Comment. You can set the string content of any PBDOM_CHARACTERDATA object after you have set it as the child of a parent.
The same process is repeated for the text and CDATA objects:
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
PBDOM_CHARACTERDATA pbdom_chardata[]
PBDOM_ELEMENT pbdom_elem
long = 0
string strXML = "<abc><data><child_1/><child_2/><child_3/></data></abc>"
TRY
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_chardata[1] = Create PBDOM_COMMENT
pbdom_chardata[2] = Create PBDOM_TEXT
pbdom_chardata[3] = Create PBDOM_CDATA
pbdom_elem = pbdom_doc.GetRootElement(). &
GetChildElement("data").GetChildElement("child_1")
pbdom_chardata[1].SetParentObject (pbdom_elem)
pbdom_chardata[1].SetText ("Comment")
pbdom_elem = pbdom_doc.GetRootElement(). &
GetChildElement("data").GetChildElement("child_2")
pbdom_chardata[2].SetParentObject (pbdom_elem)
pbdom_chardata[2].SetText ("Text")
pbdom_elem = pbdom_doc.GetRootElement(). &
GetChildElement("data").GetChildElement("child_3")
pbdom_chardata[3].SetParentObject (pbdom_elem)
pbdom_chardata[3].SetText ("CDATA")
pbdom_doc.SaveDocument ("c:\pbdom_doc_1.xml")
Destroy pbdombuilder_new
CATCH (PBDOM_Exception except)
MessageBox ("Exception Occurred", except.Text)
END TRY
When the PBDOM_DOCUMENT is saved to a file, the output DOM tree looks like this:
<abc> <data> <child_1> <!--Comment--> </child_1> <child_2> Text </child_2> <child_3> <![CDATA[CDATA]]> </child_3> </data> </abc>
The PBDOM_OBJECT that you set to be the parent of the current PBDOM_CHARACTERDATA must have a legal parent-child relationship. If it does not, an exception is thrown.
The SetText method sets the input string to be the text content of the current PBDOM_CHARACTERDATA object.
pbdom_chardata_name.SetText(string strSet)
Argument |
Description |
|---|---|
pbdom_chardata_name |
The name of a PBDOM_CHARACTERDATA |
strSet |
The string you want set as the text of the PBDOM_CHARACTERDATA |
PBDOM_CHARACTERDATA. The current PBDOM_CHARACTERDATA object modified.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
The SetText method sets the input string to be the text content of the current PBDOM_CHARACTERDATA object.
