PBDOM_CHARACTERDATA

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")//error

In 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")//success

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_CHARACTERDATA

GetContent

false

InsertContent

current PBDOM_CHARACTERDATA

RemoveContent

false

SetContent

current PBDOM_CHARACTERDATA

SetName

false


PBDOM_CHARACTERDATA has the following non-trivial methods:


Append

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

For this syntax

See

Append(string strAppend)

Append Syntax 1 

Append(pbdom_characterdata pbdom_characterdata_ref)

Append Syntax 2 


Append Syntax 1

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:

  1. 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.

  2. 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.

  3. 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.

  4. 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 TRY

The 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>

Append Syntax 2

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.

Clone

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 if

However, 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 TRY

Usage

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.

Detach

Description

Detaches a PBDOM_CHARACTERDATA object from its parent.

Syntax

pbdom_chardata_name.Detach()

Argument

Description

pbdom_chardata_name

The name of a 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.

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 TRY

When 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.

Equals

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

Clone

GetOwnerDocumentObject

Description

The GetOwnerDocumentObject method returns the owning PBDOM_DOCUMENT of the current PBDOM_CHARACTERDATA.

Syntax

pbdom_chardata_name.GetOwnerDocumentObject()

Argument

Description

pbdom_chardata_name

The name of a PBDOM_CHARACTERDATA object


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

  1. 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
  2. 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

GetParentObject

SetParentObject

GetName

Description

The GetName method allows you to obtain the name of the current PBDOM_CHARACTERDATA.

Syntax

pbdom_chardata_name.GetName()

Argument

Description

pbdom_chardata_name

The name of a PBDOM_CHARACTERDATA object


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.

DOM Object

Return Value

PBDOM_CDATA

"#cdata-section"

PBDOM_COMMENT

"#comment"

PBDOM_TEXT

"#text"


GetObjectClass

Description

The GetObjectClass method 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 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

GetObjectClassString

GetObjectClassString

Description

The GetObjectClassString method 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.

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 &lt; character      <!-- Comment with a &lt; character -->
      <![CDATA[ CDATA with an actual > character and 
        an entity reference &lt; ]]>
   </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 &lt; 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 &lt; character<!-- Comment with a &lt; character --><![CDATA[ CDATA with an actual > character and an entity reference &lt; ]]></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 TRY

See also

GetObjectClass

GetParentObject

Description

The GetParentObject method returns the parent PBDOM_OBJECT of the current PBDOM_CHARACTERDATA.

Syntax

pbdom_chardata_name.GetParentObject()

Argument

Description

pbdom_chardata_name

The name of a 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.

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 TRY

When 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

SetParentObject

GetText

Description

Calling the GetText method allows you to obtain text data that is contained within the current PBDOM_CHARACTERDATA.

Syntax

pbdom_chardata_name.GetText()

Argument

Description

pbdom_chardata_name

The name of a PBDOM_CHARACTERDATA object


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

GetTextNormalize

GetTextTrim

SetText

GetTextNormalize

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()

Argument

Description

pbdom_chardata_name

The name of a PBDOM_CHARACTERDATA object


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:

  1. Using an external general parsed entity.

  2. Using a single line statement to obtain the children PBDOM_OBJECTs of an element.

  3. Obtaining the text of the three separate types of PBDOM_CHARACTERDATA objects : PBDOM_TEXT, PBDOM_COMMENT, and PBDOM_CDATA.

  4. Obtaining the normalized text of the same three separate types of PBDOM_CHARACTERDATA objects.

  5. The difference between the two types of text retrieved in 3 and 4.

Suppose the file C:\entity_text.txt contains the following string:

&#9;&#32;Some&#32;External&#32;&#32;&#9;&#32;Text&#32;&#9;

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 TRY

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

The GetTextTrim method returns the textual content of the current PBDOM_CHARACTERDATA object with all surrounding whitespace characters removed.

Syntax

pbdom_chardata_name.GetTextTrim()

Argument

Description

pbdom_chardata_name

The name of a PBDOM_CHARACTERDATA


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:

  1. Using an External DTD.

  2. Using a parameter entity.

  3. Using a single line statement to obtain the children PBDOM_OBJECTs of an element.

  4. Obtaining the text of the three separate types of PBDOM_CHARACTERDATA objects : PBDOM_TEXT, PBDOM_COMMENT, and PBDOM_CDATA.

  5. Obtaining the trimmed text of the same three separate types of PBDOM_CHARACTERDATA objects.

  6. 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:

&#32;&#32;&#32;PARAMETER ENTITY REFERENCE&#9;&#9;&#9;

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 ~"&#32;&#32;&#32;PARAMETER ENTITY REFERENCE&#9;&#9;&#9;~"><!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 TRY

Usage

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

See also

GetText

GetTextNormalize

SetText

HasChildren

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()

Argument

Description

pbdom_chardata_name

The name of a PBDOM_CHARACTERDATA.


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.

IsAncestorObjectOf

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.

SetParentObject

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 TRY

When 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

GetParentObject

SetText

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

GetText

GetTextNormalize

GetTextTrim