The PBDOM_TEXT class represents a DOM Text Node within an XML document. It extends the PBDOM_CHARACTERDATA class with a set of methods specifically intended for manipulating DOM text nodes.
The PBDOM_TEXT class is derived from the PBDOM_CHARACTERDATA class. PBDOM_TEXT objects are commonly used to represent the textual content of a PBDOM_ELEMENT or PBDOM_ATTRIBUTE.
Whitespace characters
The text in a PBDOM_TEXT object can include whitespace
characters such as carriage returns, linefeeds, tabs, and spacebar
spaces.
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_TEXT |
GetContent |
false |
GetName |
a string “#text” |
HasChildren |
false |
InsertContent |
current PBDOM_TEXT |
IsAncestorObjectOf |
false |
RemoveContent |
false |
SetContent |
current PBDOM_TEXT |
SetName |
false |
PBDOM_TEXT 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_TEXT object.
Syntax 2 appends the text data of a PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_TEXT 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_TEXT object.
pbdom_text_name.Append(string strAppend)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
strAppend |
The string you want appended to the existing text of the current PBDOM_TEXT object |
PBDOM_CHARACTERDATA. The current PBDOM_TEXT object modified and returned as a PBDOM_CHARACTERDATA object.
Appends the text data of a PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_TEXT object.
pbdom_text_name.Append(pbdom_characterdata pbdom_characterdata_ref)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
pbdom_characterdata_ref |
The referenced PBDOM_CHARACTERDATA object whose text data is to be appended to the existing text of the current PBDOM_TEXT object |
PBDOM_CHARACTERDATA. The current PBDOM_TEXT object modified and returned as a PBDOM_CHARACTERDATA object.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_CHARACTERDATA is not a reference to an object inherited from PBDOM_CHARACTERDATA.
Note that JDOM does not define an Append method for its TEXT class. Because PBDOM implements its Append method in the base PBDOM_CHARACTERDATA class, a PBDOM_COMMENT object, a PBDOM_CDATA object, and a PBDOM_TEXT object can append their internal text data to each other, because they are all objects inherited from PBDOM_CHARACTERDATA.
Creates and returns a clone of the current PBDOM_TEXT object.
pbdom_text_name.Clone(boolean bDeep)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object. |
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 parameter is ignored. |
PBDOM_OBJECT. The return value is a clone of the current PBDOM_TEXT object returned as a PBDOM_OBJECT.
This example creates an XML document that, when serialized, appears as follows :
<!DOCTYPE root [ <!ELEMENT root (child_1, child_2)> <!ELEMENT child_1 (#PCDATA)*> <!ELEMENT child_2 (#PCDATA)*> ]> <root> <child_1>text for child.</child_1> <child_2>text for child.</child_2> </root>
The definition of the DTD shows that the document is required to have the following composition:
The document contains a root element with the name root.
The root element contains a sequence of two child elements named child_1 and child_2.
Both child_1 and child_2 contain only text.
The following PowerScript code creates a PBDOM_TEXT object and assigns it a text value. It then creates a child_1 element, adds the PBDOM_TEXT object to it, creates a shallow clone of child_1, and names the clone child_2. After adding a clone of the text object to child_2, the code adds both child objects to the root element:
PBDOM_BUILDER pbdom_buildr
PBDOM_DOCUMENT pbdom_doc
PBDOM_ELEMENT pbdom_elem_child_1
PBDOM_ELEMENT pbdom_elem_child_2
PBDOM_TEXT pbdom_txt
string strXML = "<!DOCTYPE root [<!ELEMENT root (child_1, child_2)><!ELEMENT child_1 (#PCDATA)><!ELEMENT child_2 (#PCDATA)>]><root/>"
try
pbdom_buildr = Create PBDOM_BUILDER
pbdom_doc = pbdom_buildr.BuildFromString (strXML)
pbdom_txt = Create PBDOM_TEXT
pbdom_txt.SetText ("text for child.")
pbdom_elem_child_1 = Create PBDOM_ELEMENT
pbdom_elem_child_1.SetName ("child_1")
pbdom_elem_child_1.AddContent (pbdom_txt)
pbdom_elem_child_2 = pbdom_elem_child_1.Clone(false)
pbdom_elem_child_2.SetName("child_2")
pbdom_elem_child_2.AddContent (pbdom_txt.Clone(false))
pbdom_doc.GetRootElement().AddContent(pbdom_elem_child_1)
pbdom_doc.GetRootElement().AddContent(pbdom_elem_child_2)
pbdom_doc.SaveDocument ("sample.xml")
catch (PBDOM_EXCEPTION pbdom_except)
MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())
end try
The Clone method creates a new PBDOM_TEXT object that is a duplicate of, and a separate object from, the original. Whether true or false is supplied as the parameter to this function, a PBDOM_TEXT clone is always identical to its original. This is because a PBDOM_TEXT does not contain any subtree of children PBDOM_OBJECTs.A PBDOM_TEXT clone has no parent. However, the clone resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_TEXT object is standalone, the clone is standalone
Detaches a PBDOM_TEXT object from its parent PBDOM_OBJECT.
pbdom_text_name.Detach()
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
PBDOM_OBJECT. The current PBDOM_TEXT object is detached from its parent.
If the current PBDOM_TEXT object has no parent, nothing happens.
Tests for the equality of the current PBDOM_TEXT object and a referenced PBDOM_OBJECT.
pbdom_text_name.Equals(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
pbdom_object_ref |
A reference to a PBDOM_OBJECT to test for equality with the current PBDOM_TEXT object |
Boolean. Returns true if the current PBDOM_TEXT object is equivalent to the input 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_TEXT object and refers to the same DOM object as the current PBDOM_TEXT object. Two separately created PBDOM_TEXT 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_TEXT object, the returned value is 7.
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_TEXT object, the returned string is “pbdom_text”.
Returns the owning PBDOM_DOCUMENT of the current PBDOM_TEXT object.
pbdom_text_name.GetOwnerDocumentObject()
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
PBDOM_OBJECT.
If there is no owning PBDOM_DOCUMENT, null is returned.
Returns the parent PBDOM_OBJECT of the current PBDOM_TEXT object.
pbdom_text_name.GetParentObject()
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
PBDOM_OBJECT.
The parent is also an object inherited from PBDOM_TEXT object. If the PBDOM_TEXT object has no parent, null is returned.
Obtains the text data that is contained within the current PBDOM_TEXT object.
pbdom_text_name.GetText()
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
String. The GetText method returns the textual content of the current PBDOM_TEXT object.
If you have the element <abc>MY
TEXT</abc>, and you have a PBDOM_TEXT
object to represent the text node “MY TEXT”, then
calling GetText on the PBDOM_TEXT object
returns the string “MY TEXT”.
Obtains the text data that is contained within the current PBDOM_TEXT object, with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.
pbdom_text_name.GetTextNormalize()
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
String.
If you have a PBDOM_TEXT object that represents
the text node “ MY TEXT ”,
calling GetTextNormalize returns the string “MY
TEXT”. All surrounding whitespaces
are removed, and the whitespaces between the words “MY” and “TEXT” are
reduced to a single space.
This method allows the caller to obtain the text data that is contained within the current PBDOM_TEXT object with all surrounding whitespaces removed and internal whitespaces normalized to single spaces. If no textual value exists for the current PBDOM_TEXT object, or if only whitespaces exist, an empty string is returned.
Returns the textual content of the current PBDOM_TEXT object with all surrounding whitespace characters removed.
pbdom_text_name.GetTextTrim()
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
String.
If you have a PBDOM_TEXT object that represents
the text node “ MY TEXT ”,
calling GetTextNormalize returns the string “MY TEXT”.
All surrounding white spaces are removed. The whitespaces between the
words “MY” and “TEXT” are
preserved.
This method allows the caller to obtain the text data that is contained within the current PBDOM_TEXT object with all surrounding whitespaces removed. Internal whitespaces are preserved. If no textual value exists for the current PBDOM_TEXT object, or if only whitespaces exist, an empty string is returned.
Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_TEXT object.
pbdom_text_name.SetParentObject(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
pbdom_object_ref |
A PBDOM_OBJECT to be set as the parent of the current PBDOM_TEXT object |
PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_OBJECT is not referenced to an object derived from PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – If the current PBDOM_TEXT object 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 PBDOM_TEXT 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_TEXT object must have a legal parent-child relationship with the current object. If it does not, an exception is thrown. Only a PBDOM_ELEMENT is allowed to be set as the parent of a PBDOM_TEXT object.
Sets the input string to be the text content of the current PBDOM_TEXT object.
pbdom_text_name.SetText(strSet)
Argument |
Description |
|---|---|
pbdom_text_name |
The name of a PBDOM_TEXT object |
strSet |
The string you want set as the text of the PBDOM_TEXT object |
String. If no DTD is referenced, an empty string is returned.
