PBDOM_DOCUMENT:
InsertContent method
Description
Inserts
a new PBDOM_OBJECT into the current PBDOM_DOCUMENT object.
Syntax
|
1 |
<span>pbdom_document_name</span>.InsertContent(pbdom_object <span>pbdom_object_new</span>, pbdom_object <span>pbdom_object_ref</span>) |
|
Argument |
Description |
|---|---|
|
pbdom_document_name |
The name of a PBDOM_DOCUMENT |
|
pbdom_object_new |
The PBDOM_OBJECT to insert |
|
pbdom_object_ref |
The PBDOM_OBJECT in front of |
Return Values
PBDOM_OBJECT. The modified PBDOM_DOCUMENT
object returned as a PBDOM_OBJECT.
Throws
EXCEPTION_INVALID_ARGUMENT – The
input PBDOM_OBJECT to insert is invalid. This can happen
if it has not been initialized properly or is a null object reference.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – The
input PBDOM_OBJECT to insert has not been given a user-defined
name. The same exception is thrown if the reference PBDOM_OBJECT
is also not given a user–defined name, unless the reference
PBDOM_OBJECT is specifically set to null.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – The
input PBDOM_OBJECT to insert is not associated with a derived PBDOM_OBJECT.
The same exception is thrown if the reference PBDOM_OBJECT
is also not associated with a derived PBDOM_OBJECT, unless
the reference PBDOM_OBJECT is specifically set to null.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – The
input PBDOM_OBJECT to insert already as a parent.
EXCEPTION_MULTIPLE_ROOT_ELEMENT – A
PBDOM_ELEMENT is to be inserted, but this document already
has a root element.
EXCEPTION_MULTIPLE_DOCTYPE – A
PBDOM_DOCTYPE is to be inserted, but this document already
has a DOCTYPE.
EXCEPTION_HIERARCHY_ERROR – Inserting
the PBDOM_OBJECT adversely affects how well-formed the
document is.
EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT – An
invalid PBDOM_OBJECT is to be inserted. See AddContent for information
on the valid PBDOM_OBJECTs that can be added to a PBDOM_DOCUMENT
object.
EXCEPTION_WRONG_PARENT_ERROR – The
reference PBDOM_OBJECT is not a child of this PBDOM_DOCUMENT
object.
Examples
A PBDOM_DOCUMENT object is created from
an XML string. The PBDOM_ELEMENT pbdom_elem_1 is
also created and set as Elem_1. The PBDOM_DOCTYPE pbdom_doctype_1 and
the root element pbdom_root_elem are
set.The root element is detached from its parent, which is also
the PBDOM_DOCUMENT object itself. This makes it possible
to insert pbdom_elem_1 into
the document specifically before pbdom_doctype_1.
|
1 |
pbdom_builder pbdom_builder_1<br>pbdom_document pbdom_doc<br>pbdom_doctype pbdom_doctype_1<br>pbdom_element pbdom_elem_1<br>pbdom_element pbdom_elem_root<br>string strXML<br> <br>strXML = "<!DOCTYPE abc [<!-- internal subset -->"<br>strXML += "<!ELEMENT abc (#PCDATA)> "<br>strXML += "<!ELEMENT data&(#PCDATA)> "<br>strXML += "<!ELEMENT inner_data (#PCDATA)>]><abc>"<br>strXML += "Root Element Data<data>ABC Data<inner_data>"<br>strXML += "My Inner Data</inner_data>My Data</data>"<br>strXML += " now with extra& info</abc>"<br> <br>pbdom_builder_1 = Create PBDOM_Builder<br>pbdom_elem_1 = Create PBDOM_Element<br> <br>pbdom_doc = pbdom_builder_1.BuildFromString (strXML)<br>pbdom_elem_1.SetName ("Elem_1")<br>pbdom_doctype_1 = pbdom_doc.GetDocType()<br>pbdom_elem_root = pbdom_doc.GetRootElement()<br> <br>pbdom_elem_root.Detach()<br>pbdom_doc.InsertContent(pbdom_elem_1, pbdom_doctype_1 |
The result is the following document, which is not well-formed:
|
1 |
<Elem_1/><br><!DOCTYPE abc[<!-- internal subset --> <br><!ELEMENT abc (#PCDATA)*> <!ELEMENT data (#PCDATA)*> <!ELEMENT inner_data (#PCDATA)*>]> |
Usage
When a new PBDOM_OBJECT is inserted into the current PBDOM_DOCUMENT
object, the new PBDOM_OBJECT becomes a child node of the
current PBDOM_DOCUMENT object. Also, the new PBDOM_OBJECT
is to be positioned specifically before another PBDOM_OBJECT,
denoted using the second parameter.
If the second PBDOM_OBJECT is specified as null,
then the new PBDOM_OBJECT is to be inserted at the end
of the list of children of the current PBDOM_DOCUMENT object.