Edit online

Inserting XML Elements

In Oxygen XML Web Author, XML elements can be inserted by using the Content Completion Assistant or by using an Author mode action that can be added to the toolbar, contextual menu, or Content Completion Assistant.

Inserting Elements Using Content Completion

When using the content completion feature, a list of elements that are valid at the current location within the document is displayed. However, showing only the valid elements might be limiting in some situations.

For example, suppose you just entered the <title> element for a <section> and you want to insert a <table>. The cursor is still located inside the <title> element and the <table> element is not valid at this position. However, it is valid immediately after the title.

To make it easier to insert elements in such cases, Oxygen XML Web Author displays all the elements, even if invalid at the current position. If an invalid element is chosen, it inserts the element in a Schema-Aware mode. This means that some strategies are applied to keep the document valid (for example, inserting the element in a nearby position or inserting a required ancestor).

Various aspects of the Content Completion assistant can be configured using either configuration files or the JavaScript or Java API.

Inserting Elements Using Author Actions

An Author mode action can be added to the toolbar, contextual menu, or Content Completion Assistant. Such an action has one or more operation modes. The evaluation of an XPath expression activates an operation mode. The first activated operation mode is executed when you trigger the action.

A simple action to insert an element can use a single operation mode with Activation XPath set to true. The operation is InsertFragmentOperation and the schemaAware parameter should be set to true. With this setup, the action inserts the element in the expected position while keeping the document valid.

If you identify some cases where the action behavior is less than optimal, you can add an another operation mode that does any of the following:

  • Has the Activation XPath configured to match the particular XML structure where you observe the undesired behavior. You can use some Oxygen XML Web Author-specific extension functions such as the oxy:allows-child-element() function.
  • Uses the InsertFragmentOperation operation.
  • Has the schemaAware parameter set to false. This allows you to precisely control the insertion point.
  • Uses the insertLocation and insertPosition parameters to specify the desired insertion location.
  • Configures the fragment parameter to the actual fragment to be inserted. This fragment should contain:
    • All the ancestors that need to be inserted to make the document valid.
    • All the required descendants of the element.
    • All the required attributes of the element.
The original operation mode should be kept later in the list as a fallback.

In more complicated cases, you may need to identify a particular cursor position that is impossible to represent in XPath (for example, when the cursor is between the title and the body of a topic. For these cases, you can use a more relaxed XPath such as .[local-name() = 'topic'] and use a custom implementation of the Java AuthorOperation interface.

Showing a Dialog Box to Configure the Newly Inserted Element

To determine how to configure an element before it is inserted, it is possible to require user input. For example, to insert a link, the user needs to choose the link target. If you want to prompt the user for input, you can use the ${ask} editor variable or use the JavaScript API.

Inserting the Correct Element Depending on the DITA Specialization

In DITA, the name of an image or link element depends on the specialization. The default toolbar actions to insert such elements use an operation such as ro.sync.ecss.extensions.dita.topic.InsertImageOperation. These operations are usually able to determine which valid element to insert depending on the DITA specialization or the cursor position.

The source code for these operations is available in the Oxygen SDK Maven repository with the following details:
  • groupId - com.oxygenxml
  • artifactId - oxygen
  • classifier - defaultFrameworkSources
For example, for version 22.0.0.0 of the SDK, the archive with the sources can be found at: https://www.oxygenxml.com/maven/com/oxygenxml/oxygen/22.0.0.0/oxygen-22.0.0.0-defaultFrameworksSources.jar.