History | Edit

fragment

This argument has a textual value. This value is parsed by Oxygen XML Editor 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:

  1. 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>
  2. 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
This argument applies only on the surround with element operation and controls whether or not the insertion is valid, based upon the schema. If the insertion is not valid, then wrapping action will be broken up into smaller intervals until the wrapping action is valid. For example, if you try to wrap a paragraph element with a bold element, it would not be valid, so the operation will wrap the text inside the paragraph instead, since it would be valid at that position.