PBDOM_CDATA

Append
Clone
Detach
Equals
GetObjectClass
GetObjectClassString
GetOwnerDocumentObject
GetParentObject
GetText
GetTextNormalize
GetTextTrim
SetParentObject
SetText

Description

The PBDOM_CDATA class represents an XML DOM CDATA section. The PBDOM_CDATA class is derived from PBDOM_TEXT, which inherits from the PBDOM_CHARACTERDATA class.

A PBDOM_CDATA object is used to hold text that contains characters that are prohibited in text objects, such as "<" and "&", without using entity references. For example, consider the following PBDOM_CDATA object:

<some_text>
   <![CDATA[ (x < y) & (y < z) => x < z ]]>
</some_text>

A PBDOM_TEXT object with the same text content must be written like this:

<some_text>
   (x &lt; y) &amp; (y &lt; z) =&gt; x &lt; z
</some_text>

However, although the PBDOM_CDATA class is derived from PBDOM_TEXT, a PBDOM_CDATA object cannot always be inserted in the same context as a PBDOM_TEXT. For example, a PBDOM_TEXT object can be added as a child of a PBDOM_ATTRIBUTE, but a PBDOM_CDATA object cannot.

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_CDATA
GetContent	false
GetName	a string "#cdata"
HasChildren	false
InsertContent	current PBDOM_CDATA
IsAncestorObjectOf	false
RemoveContent	false
SetContent	current PBDOM_CDATA
SetName	false

PBDOM_CDATA has the following non-trivial methods:

GetOwnerDocumentObject

Append

Description

Appends the input string or the input text data of the PBDOM_CHARACTERDATA object to the text content that already exists within the current PBDOM_CDATA object.

Syntax

pbdom_cdata_name.Append(string strAppend)
pbdom_cdata_name.Append(pbdom_characterdata pbdom_characterdata_ref)

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA
strAppend	The string you want appended to the existing text of the current PBDOM_CDATA object
pbdom_characterdata_ref	The referenced PBDOM_CHARACTERDATA object whose text data is to be appended to the existing text of the current PBDOM_CDATA object

Return value

PBDOM_CHARACTERDATA.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the input PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA (applies to second syntax).

Clone

Description

Creates and returns a clone of the current PBDOM_CDATA.

Syntax

pbdom_cdata_name.Clone(boolean bDeep)

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA.
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. The return value is a clone of the current PBDOM_CDATA housed in a PBDOM_OBJECT.

Examples

This example tests the following characteristics of a cloned PBDOM_CDATA object:

The contents of an original and cloned PBDOM_CDATA object are exactly the same
A cloned PBDOM_CDATA initially has no parent object

A cloned PBDOM_CDATA is initially contained within the same owner document as the original

PBDOM_BUILDER     pbdom_buildr
PBDOM_DOCUMENT    pbdom_doc
PBDOM_CDATA       pbdom_cdat
PBDOM_OBJECT      pbdom_obj_array[]
string strXML = "<!DOCTYPE root [<!ELEMENT root (#PCDATA)>]><root><![CDATA[This is a CDATA Section.]]></root>"

try
  // Build a PBDOM_DOCUMENT based on strXML.
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)

  // Get the contents of the root element.
  pbdom_doc.GetRootElement().GetContent(pbdom_obj_array)
  
  // Test if the root element contains only one child object.
  if (UpperBound(pbdom_obj_array) = 1) then
    MessageBox ("Pass", "Root Element has only one child.")
  else
    MessageBox ("Fail", "Root Element must have only one child.")
  end if

  // Make a clone of the only child of the root element.
  pbdom_cdat = pbdom_obj_array[1].Clone(true)

  // Test if the clone is a PBDOM_CDATA object.
  if (pbdom_cdat.GetObjectClassString() = "pbdom_cdata") then
    MessageBox ("Pass", &
     "The first child, after being cloned, is indeed a PBDOM_CDATA object.")
  else
    MessageBox ("Fail", "The first child, after being cloned, " &
      + "is found to be a " + pbdom_cdat.GetObjectClassString() + " object.")
  end if

  // Test if the clone is a CDATA section.
  if (pbdom_cdat.GetText() = "This is a CDATA Section.") then
    MessageBox ("Pass", "The text contents of the clone is correct.")
  else
    MessageBox ("Fail", "The text contents of the clone is : [" &
      + pbdom_cdat.GetText() + "]. This is incorrect.")
  end if
  
  // Test that the clone has no parent.
  if (Not IsValid(pbdom_cdat.GetParentObject())) then
    MessageBox ("Pass", "The clone has no parent.")
  else
    MessageBox ("Fail", "The clone should have no parent.")
  end if
  
  // Test that the clone's owner document is the same 
  // as the original's owner document.
  if (pbdom_cdat.GetOwnerDocumentObject() = pbdom_doc) then
    MessageBox ("Pass", "The clone's owner document is correct.")
  else
    MessageBox ("Fail", "The clone's owner document is incorrect.")
  end if
  
catch (PBDOM_EXCEPTION pbdom_except)
  MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())
end try

Usage

The Clone method creates a new PBDOM_CDATA object that is a duplicate of, and a separate object from, the original. The clone of a PBDOM_CDATA is always identical to its original whether deep or shallow cloning is invoked, because a PBDOM_CDATA object does not contain any subtree of child PBDOM_OBJECTs.

A PBDOM_CDATA clone has no parent. However, the clone resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_CDATA is standalone, the clone is standalone.

Detach

Description

Detaches a PBDOM_CDATA from its parent PBDOM_OBJECT.

Syntax

pbdom_cdata_name.Detach()

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA

Return value

PBDOM_OBJECT. The current PBDOM_CDATA detached from its parent.

Usage

If the current PBDOM_CDATA object has no parent, no modifications occur.

Equals

Description

Tests for the equality of the current PBDOM_CDATA and a referenced PBDOM_OBJECT.

Syntax

pbdom_cdata_name.Equals(pbdom_object pbdom_object_ref)

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA
pbdom_object_ref	A PBDOM_OBJECT to test for equality with the current PBDOM_CDATA

Return value

Boolean.

Returns true if the current PBDOM_CDATA object is equivalent to the referenced 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_CDATA object and refers to the same DOM object as the current PBDOM_CDATA. Two separately created PBDOM_CDATA objects, for example, can contain exactly the same text but not be equal.

GetObjectClass

Description

Returns a long integer code that indicates the class of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClass()

Argument	Description
pbdom_object_name	The name of a PBDOM_OBJECT

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_CDATA object, the returned value is 8.

See also

GetObjectClassString

Description

Returns a string form of the class of the PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClassString()

Argument	Description
pbdom_object_name	The name of a PBDOM_OBJECT

Return value

String.

GetObjectClassString returns a string that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_CDATA object, the returned string is "pbdom_cdata".

See also

GetObjectClass

GetOwnerDocumentObject

Description

Returns the owning PBDOM_DOCUMENT of the current PBDOM_CDATA.

Syntax

pbdom_cdata_name.GetOwnerDocumentObject()

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA

Return value

PBDOM_OBJECT.

Usage

If there is no owning PBDOM_DOCUMENT, null is returned.

See also

GetParentObject

SetParentObject

GetParentObject

Description

Returns the parent PBDOM_OBJECT of the PBDOM_CDATA. If there is no parent, null is returned.

Syntax

pbdom_cdata_name.GetParentObject()

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA

Return value

PBDOM_OBJECT.

See also

GetOwnerDocumentObject

SetParentObject

GetText

Description

Returns the text data that is contained within the current PBDOM_CDATA object.

Syntax

pbdom_cdata_name.GetText()

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA

Return value

String.

The textual content of the current PBDOM_CDATA object.

See also

GetTextNormalize

GetTextTrim

SetText

GetTextNormalize

Description

Returns the text data that is contained within the current PBDOM_CDATA object, with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.

Syntax

pbdom_cdata_name.GetTextNormalize()

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA

Return value

String.

Usage

If no textual value exists for the current PBDOM_OBJECT, or if only whitespace characters exist, an empty string is returned.

See also

GetText

GetTextTrim

SetText

GetTextTrim

Description

Returns the textual content of the current PBDOM_CDATA object with all surrounding whitespace characters removed.

Syntax

pbdom_cdata_name.GetTextTrim()

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA

Return value

String.

Usage

If no textual value exists for the current PBDOM_CDATA, or if only whitespace characters exist, an empty string is returned.

See also

GetText

GetTextNormalize

SetText

SetParentObject

Description

Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_CDATA.

Syntax

pbdom_cdata_name.SetParentObject(pbdom_object pbdom_object_ref)

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA
pbdom_object_ref	A PBDOM_OBJECT to be set as the parent of this PBDOM_CDATA object

Return value

PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- 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_CDATA already has a parent.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT -- If the input PBDOM_OBJECT is of a class that does not have a legal parent-child relationship with the PBDOM_CDATA 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_CDATA must have a legal parent-child relationship. If it does not, an exception is thrown. Only a PBDOM_ELEMENT object can be set as the parent of a PBDOM_CDATA object.

See also

GetParentObject

SetText

Description

Sets the input string to be the text content of the current PBDOM_CDATA object.

Syntax

pbdom_cdata_name.SetText(string strSet)

Argument	Description
pbdom_cdata_name	The name of a PBDOM_CDATA
strSet	The string you want set as the text of the PBDOM_CDATA

Return value

PBDOM_CHARACTERDATA. This PBDOM_CDATA modified and returned as a PBDOM_CHARACTERDATA object.

See also

GetText

GetTextNormalize

GetTextTrim

Prev	Up	Next
PBDOM_CDATA Class	Home	PBDOM_ENTITYREFERENCE Class

PowerBuilder Extension ReferencePBDOM_CDATA Class

PBDOM_CDATA

Append

Clone

Detach

Equals

GetObjectClass

GetObjectClassString

GetOwnerDocumentObject

GetParentObject

GetText

GetTextNormalize

GetTextTrim

SetParentObject

SetText

PowerBuilder Extension Reference
PBDOM_CDATA Class