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
