Arguments of InsertFragmentOperation

fragment

This argument has a textual value. This value is parsed by Oxygen XML as it was already in the document at the cursor position. You can use entity references declared in the document and it is namespace aware. The fragment may have multiple roots.

You can even use namespace prefixes that are not declared in the inserted fragment, if they are declared in the document where the insertion is done. For the sake of clarity, you should always prefix and declare namespaces in the inserted fragment!

If the fragment contains namespace declarations that are identical to those found in the document, the namespace declaration attributes will be removed from elements contained by the inserted fragment.

There are two possible scenarios:

Prefixes that are not bound explicitly

For instance, the fragment:

<x:item id="dty2"/>
&ent;
<x:item id="dty3"/>

Can be correctly inserted in the document: ('|' marks the insertion point):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE x:root [
    <!ENTITY ent "entity">
]>

<x:root xmlns:x="nsp"> 
  |
</x:root>

Result:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE x:root [
    <!ENTITY ent "entity">
]>
<x:root xmlns:x="nsp">
    <x:item id="dty2"/>
    &ent;
    <x:item id="dty3"/>
</x:root>

Default namespaces

If there is a default namespace declared in the document and the document fragment does not declare a namespace, the elements from the fragment are considered to be in no namespace.
For instance, the fragment:
```
<item id="dty2"/>
<item id="dty3"/>
```
Inserted in the document:
```
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="nsp">
|
</root>
```
Gives the result document:
```
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="nsp">
    <item xmlns="" id="dty2"/>
    <item xmlns="" id="dty3"/>
</root>
```

insertLocation

An XPath expression that is relative to the current node. It selects the reference node for the fragment insertion. When missing, the fragment will be inserted at the cursor position.

insertPosition

Specifies where the insertion is made relative to the reference node selected by the insertLocation. It can be one of the following constants:

Inside as first child (default value) - The fragment is inserted as first child of the reference node.
Inside as last child - The fragment is inserted as the last child of the reference node.
After - The fragment is inserted after the reference node.
Before - The fragment is inserted before the reference node.

goToNextEditablePosition

After inserting the fragment, the first editable position is detected and the cursor is placed at that location. It handles any in-place editors used to edit attributes. It will be ignored if the fragment specifies a cursor position using the ${caret} editor variable. The possible values of this action are true and false.

schemaAware

insertEvenIfInvalid

The possible values of this argument are true and false. If true, the content that would make the document invalid is accepted. If false and the insertion is not valid, the operation will not be executed and an error message will be displayed.