Description
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")//errorIn 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")//successMethods
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:
Description
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.
Syntax
Description
Appends an input string to the text content that already exists within the current PBDOM_CHARACTERDATA object.
Syntax
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 |
Return value
PBDOM_CHARACTERDATA. The current PBDOM_CHARACTERDATA modified and returned as a PBDOM_CHARACTERDATA object.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA object is not a reference to an object derived from PBDOM_CHARACTERDATA.
Examples
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 TRYThe 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>
Description
Appends the text data of a PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_CHARACTERDATA object.
Syntax
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 |
Return value
PBDOM_CHARACTERDATA. The current PBDOM_CHARACTERDATA modified and returned as a PBDOM_CHARACTERDATA object.
Throws
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.
Usage
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.
Description
Creates and returns a clone of the current PBDOM_CHARACTERDATA.
Syntax
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. |
Return value
PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Examples
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 ifHowever, 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 TRYUsage
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.
Description
Detaches a PBDOM_CHARACTERDATA object from its parent.
Syntax
pbdom_chardata_name.Detach()
Return value
PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Examples
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 TRYWhen 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>
Usage
Nothing occurs if the PBDOM_CHARACTERDATA object has no parent.
Description
Tests for the equality of the current PBDOM_CHARACTERDATA and a referenced PBDOM_OBJECT.
Syntax
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 |
Return value
Boolean.
Returns true if the current PBDOM_CHARACTERDATA is equivalent to the input PBDOM_OBJECT and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Usage
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.
See also
Description
The GetOwnerDocumentObject method returns the owning PBDOM_DOCUMENT of the current PBDOM_CHARACTERDATA.
Syntax
pbdom_chardata_name.GetOwnerDocumentObject()
Return value
PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not associated with a derived PBDOM_CHARACTERDATA class.
Examples
-
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
Usage
If there is no owning PBDOM_DOCUMENT, null is returned.
See also
Description
The GetName method allows you to obtain the name of the current PBDOM_CHARACTERDATA.
Syntax
pbdom_chardata_name.GetName()
Return value
String.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Usage
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.
Description
The GetObjectClass method returns a long integer code that indicates the class of the current PBDOM_OBJECT.
Syntax
pbdom_object_name.GetObjectClass()
Return value
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.
See also
Description
The GetObjectClassString method returns a string form of the class of the PBDOM_OBJECT.
Syntax
pbdom_object_name.GetObjectClassString()
Return value
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.
Examples
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 TRYSee also
Description
The GetParentObject method returns the parent PBDOM_OBJECT of the current PBDOM_CHARACTERDATA.
Syntax
pbdom_chardata_name.GetParentObject()
Return value
PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Examples
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 TRYWhen the resulting PBDOM_DOCUMENT is saved to a file, it looks like this:
<abc> <data> <!-- Some Comments --> </data> </abc>
Usage
The parent is also an object derived from PBDOM_CHARACTERDATA. If the PBDOM_OBJECT has no parent, null is returned.
See also
Description
Calling the GetText method allows you to obtain text data that is contained within the current PBDOM_CHARACTERDATA.
Syntax
pbdom_chardata_name.GetText()
Return value
String.
The text of the current PBDOM_CHARACTERDATA-derived object.
Throws
Throws EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Usage
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 MY TEXT. |
|
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. |
See also
Description
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.
Syntax
pbdom_chardata_name.GetTextNormalize()
Return value
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 MY TEXT. |
|
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 |
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Examples
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 TRYUsage
If no textual value exists for the current PBDOM_OBJECT, or if only whitespace characters exist, an empty string is returned.
See also
Description
The GetTextTrim method returns the textual content of the current PBDOM_CHARACTERDATA object with all surrounding whitespace characters removed.
Syntax
pbdom_chardata_name.GetTextTrim()
Return value
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 MY TEXT. |
|
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. |
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Examples
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 TRYUsage
If no textual value exists for the current PBDOM_CHARACTERDATA, or if only whitespace characters exist, an empty string is returned.
See also
Description
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.
Syntax
pbdom_chardata_name.HasChildren()
Return value
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 |
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Usage
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.
Description
The IsAncestorObjectOf method determines whether the current PBDOM_CHARACTERDATA is the ancestor of another PBDOM_OBJECT.
Syntax
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 |
Return value
Boolean.
Returns true if the current PBDOM_CHARACTERDATA is the ancestor of the referenced PBDOM_OBJECT, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Usage
Currently, false is always returned because no subclasses of PBDOM_CHARACTERDATA contain child nodes. Therefore, they cannot be ancestors of a PBDOM_OBJECT.
Description
The SetParentObject method sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_CHARACTERDATA.
Syntax
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 |
Return value
PBDOM_OBJECT.
Throws
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.
Examples
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 TRYWhen 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>
Usage
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.
See also
Description
The SetText method sets the input string to be the text content of the current PBDOM_CHARACTERDATA object.
Syntax
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 |
Return value
PBDOM_CHARACTERDATA. The current PBDOM_CHARACTERDATA object modified.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.
Usage
The SetText method sets the input string to be the text content of the current PBDOM_CHARACTERDATA object.
See also
