Handling Schema-Aware Editing Events

The AuthorSchemaAwareEditingHandlerAdapter extension point allows you to handle certain Author mode actions in various ways. For example, implementing the AuthorSchemaAwareEditingHandlerAdapter makes it possible to handle events such as typing, the keyboard delete event at a given offset (using Delete or Backspace keys), delete element tags, delete selection, join elements, or paste fragment. It also makes it possible to improve solutions that are proposed by the paste mechanism in Oxygen XML Author Eclipse plugin when pasting content (through the use of some specific methods).

How to Implement an AuthorSchemaAwareEditingHandlerAdapter

For this handler to be called, the Schema-Aware Editing option must be set to On or Custom in the Schema-Aware preferences page. The handler can either resolve a specific case, let the default implementation take place, or reject the edit entirely by throwing an InvalidEditException.

To implement your own AuthorSchemaAwareEditingHandlerAdapter, follow this procedure:

Implement the ro.sync.ecss.extensions.api.AuthorSchemaAwareEditingHandlerAdapter extension.
To instruct Oxygen XML Author Eclipse plugin to use this newly created implementation, configure an extensions bundle and return the AuthorSchemaAwareEditingHandlerAdapter implementation using the ro.sync.ecss.extensions.api.ExtensionsBundle.getAuthorSchemaAwareEditingHandlerAdapter() method.

Example

Typing events can be handled using the handleTyping method. For example, the AuthorSchemaAwareEditingHandler checks if the schema is not a learned one, was loaded successfully, and if the Smart paste and drag and drop option is selected. If these conditions are met, the event will be handled.

public class AuthorSchemaAwareEditingHandlerAdapter 
              extends AuthorSchemaAwareEditingHandler {

/**
 * @see AuthorSchemaAwareEditingHandler#handleTyping
(int, char, ro.sync.ecss.extensions.api.AuthorAccess)
 */
public boolean handleTyping(int offset, char ch, AuthorAccess authorAccess)
throws InvalidEditException {
  boolean handleTyping = false;
  AuthorSchemaManager authorSchemaManager = 
authorAccess.getDocumentController().getAuthorSchemaManager();
  if (!authorSchemaManager.isLearnSchema() && 
      !authorSchemaManager.hasLoadingErrors() &&
      authorSchemaManager.getAuthorSchemaAwareOptions().isEnableSmartTyping()) {
    try {
      AuthorDocumentFragment characterFragment = 
authorAccess.getDocumentController().createNewDocumentTextFragment
(String.valueOf(ch));    
      handleTyping = handleInsertionEvent
(offset, new AuthorDocumentFragment[] {characterFragment}, authorAccess);
    } catch (AuthorOperationException e) {
      throw new InvalidEditException
(e.getMessage(), "Invalid typing event: " + e.getMessage(), e, false);
    }
  }
  return handleTyping;    
}

Note: The complete source code for framework customization examples can be found in the oxygen-sample-framework module of the Oxygen SDK, available as a Maven archetype on the Oxygen XML Author Eclipse plugin website.

Methods for Improving the Paste Mechanism

getAncestorDetectionOptions: When pasting content in Author mode, if the result causes the document to become invalid, Oxygen XML Author Eclipse plugin will propose solutions to make it valid. As a possible solution, Oxygen XML Author Eclipse plugin might surround the pasted content in a sequence of ancestor elements. This getAncestorDetectionOptions method allows you to choose which parent elements might be a possible solution.
canBeReplaced: Allows you to improve solutions that might be proposed by the paste mechanism when pasting content in Oxygen XML Author Eclipse plugin. For example, when pasting an element inside an empty element with the same name, this canBeReplaced method allows Oxygen XML Author Eclipse plugin to replace the empty node rather than pasting it after or before the empty node. The callback could also reject this behavior if, for instance, the replacement node contains attributes.