Description
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.
Methods
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:
Description
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.
Syntax
Description
Appends an input string to the text content that already exists within the current PBDOM_TEXT object.
Syntax
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 |
Return value
PBDOM_CHARACTERDATA. The current PBDOM_TEXT object modified and returned as a PBDOM_CHARACTERDATA object.
Description
Appends the text data of a PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_TEXT object.
Syntax
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 |
Return value
PBDOM_CHARACTERDATA. The current PBDOM_TEXT object modified and returned as a PBDOM_CHARACTERDATA object.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the input PBDOM_CHARACTERDATA is not a reference to an object inherited from PBDOM_CHARACTERDATA.
Usage
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.
Description
Creates and returns a clone of the current PBDOM_TEXT object.
Syntax
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. |
Return value
PBDOM_OBJECT. The return value is a clone of the current PBDOM_TEXT object returned as a PBDOM_OBJECT.
Examples
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 tryUsage
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
Description
Detaches a PBDOM_TEXT object from its parent PBDOM_OBJECT.
Syntax
pbdom_text_name.Detach()
Return value
PBDOM_OBJECT. The current PBDOM_TEXT object is detached from its parent.
Usage
If the current PBDOM_TEXT object has no parent, nothing happens.
Description
Tests for the equality of the current PBDOM_TEXT object and a referenced PBDOM_OBJECT.
Syntax
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 |
Return value
Boolean.
Returns true if the current PBDOM_TEXT object is equivalent to the input PBDOM_OBJECT, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
Usage
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.
Description
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 code that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_TEXT object, the returned value is 7.
See also
Description
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. If pbdom_object_name is a PBDOM_TEXT object, the returned string is "pbdom_text".
See also
Description
Returns the owning PBDOM_DOCUMENT of the current PBDOM_TEXT object.
Syntax
pbdom_text_name.GetOwnerDocumentObject()
Return value
PBDOM_OBJECT.
Usage
If there is no owning PBDOM_DOCUMENT, null is returned.
Description
Returns the parent PBDOM_OBJECT of the current PBDOM_TEXT object.
Syntax
pbdom_text_name.GetParentObject()
Return value
PBDOM_OBJECT.
Usage
The parent is also an object inherited from PBDOM_TEXT object. If the PBDOM_TEXT object has no parent, null is returned.
See also
Description
Obtains the text data that is contained within the current PBDOM_TEXT object.
Syntax
pbdom_text_name.GetText()
Return value
String.
The GetText method returns the textual content of the current PBDOM_TEXT object.
Examples
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".
See also
Description
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.
Syntax
pbdom_text_name.GetTextNormalize()
Return value
String.
Examples
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.
Usage
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.
See also
Description
Returns the textual content of the current PBDOM_TEXT object with all surrounding whitespace characters removed.
Syntax
pbdom_text_name.GetTextTrim()
Return value
String.
Examples
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.
Usage
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.
See also
Description
Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_TEXT object.
Syntax
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 |
Return value
PBDOM_OBJECT.
Throws
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.
Usage
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.
See also
Description
Sets the input string to be the text content of the current PBDOM_TEXT object.
Syntax
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 |
Return value
String.
If no DTD is referenced, an empty string is returned.
See also
