PBDOM_TEXT

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:


Append

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

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

Append Syntax 2

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.

Clone

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 try

Usage

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

Detach

Description

Detaches a PBDOM_TEXT object from its parent PBDOM_OBJECT.

Syntax

pbdom_text_name.Detach()

Argument

Description

pbdom_text_name

The name of a PBDOM_TEXT object


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.

Equals

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.

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

See also

GetObjectClassString

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_TEXT object, the returned string is "pbdom_text".

See also

GetObjectClass

GetOwnerDocumentObject

Description

Returns the owning PBDOM_DOCUMENT of the current PBDOM_TEXT object.

Syntax

pbdom_text_name.GetOwnerDocumentObject()

Argument

Description

pbdom_text_name

The name of a PBDOM_TEXT object


Return value

PBDOM_OBJECT.

Usage

If there is no owning PBDOM_DOCUMENT, null is returned.

GetParentObject

Description

Returns the parent PBDOM_OBJECT of the current PBDOM_TEXT object.

Syntax

pbdom_text_name.GetParentObject()

Argument

Description

pbdom_text_name

The name of a PBDOM_TEXT object


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

SetParentObject

GetText

Description

Obtains the text data that is contained within the current PBDOM_TEXT object.

Syntax

pbdom_text_name.GetText()

Argument

Description

pbdom_text_name

The name of a PBDOM_TEXT object


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

GetTextNormalize

GetTextTrim

SetText

GetTextNormalize

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

Argument

Description

pbdom_text_name

The name of a PBDOM_TEXT object


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

GetText

GetTextTrim, SetText

GetTextTrim

Description

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

Syntax

pbdom_text_name.GetTextTrim()

Argument

Description

pbdom_text_name

The name of a PBDOM_TEXT object


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

GetText

GetTextNormalize

SetText

SetParentObject

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

GetParentObject

SetText

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

GetText

GetTextNormalize

GetTextTrim