Package ro.sync.ecss.extensions.api

Class AuthorDocumentFilter

  • @API(type=EXTENDABLE,
     src=PUBLIC)
public class AuthorDocumentFilter
extends java.lang.Object
    AuthorDocumentFilter, is a filter for the methods which modify the AuthorDocument. When the AuthorDocument is modified through the methods from the AuthorDocumentController, the appropriate method invocation is forwarded to the AuthorDocumentFilter. The default implementation allows the modification to occur. Subclasses can filter the modifications by conditionally invoking methods on the superclass, or invoking the necessary methods on the passed in AuthorDocumentFilterBypass.

    Warning: Subclasses should NOT call back into the AuthorDocumentController for modifications in the document instead call into the superclass or the AuthorDocumentFilterBypass!

    When methods are invoked on the AuthorDocumentFilter, the AuthorDocumentFilter may callback into the AuthorDocumentFilterBypass multiple times, or for different regions, but it should not callback into the AuthorDocumentFilterBypass after returning from the initially called method.

    If you are working with framework level API, a good place to add an AuthorDocumentFilter in on AuthorExtensionStateListener.activated(AuthorAccess) notification.

    If you are working with plugin level API you can add an AuthorDocumentFilter in an Workspace Access plugin: 

       public void applicationStarted(final StandalonePluginWorkspace pluginWorkspaceAccess) {
    pluginWorkspaceAccess.addEditorChangeListener(
        new WSEditorChangeListener() {
          public void editorOpened(URL editorLocation) {
            WSEditor editorAccess = pluginWorkspaceAccess.getEditorAccess(editorLocation, PluginWorkspace.MAIN_EDITING_AREA);
            WSEditorPage currentPage = editorAccess.getCurrentPage();
            if (currentPage instanceof WSAuthorEditorPage) {
              WSAuthorEditorPage authorEditorPage = (WSAuthorEditorPage) currentPage;
              authorEditorPage.getAuthorAccess().getDocumentController().setDocumentFilter(authorDocumentFilter);
            }
            // It's also a good idea to listener for page changes on the editor.
            // Perhaps the editor opens in the text page and the user switches later on to author.
            editorAccess.addPageChangedListener(new WSEditorPageChangedListener() {
              public void editorPageChanged() {
                // Same code here to add the filter.
              }
            });
          }
        },
        PluginWorkspace.MAIN_EDITING_AREA);

    • Constructor Detail

      • AuthorDocumentFilter

        public AuthorDocumentFilter()

    • Method Detail

      • insertText

        public void insertText​(AuthorDocumentFilterBypass filterBypass,
                       int offset,
                       java.lang.String toInsert)
        Invoked before inserting the specified text at the given offset.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        offset - The offset where the text will be inserted. 0 based.
        toInsert - The text to be inserted.

      • insertFragment

        public void insertFragment​(AuthorDocumentFilterBypass filterBypass,
                           int offset,
                           AuthorDocumentFragment frag)
        Invoked before inserting an AuthorDocumentFragment at the specified offset.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        offset - The offset where the fragment will be inserted. 0 based.
        frag - The AuthorDocumentFragment to be inserted.

      • insertNode

        public boolean insertNode​(AuthorDocumentFilterBypass filterBypass,
                          int offset,
                          AuthorNode node)
        Invoked before inserting a simple node into the document.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        offset - The offset where the node should be inserted. 0 based.
        node - The AuthorNode to be inserted.
        Returns:
        true if the insert node operation succeeded.

      • insertMultipleElements

        public void insertMultipleElements​(AuthorDocumentFilterBypass filterBypass,
                                   AuthorElement parentElement,
                                   java.lang.String[] elementNames,
                                   int[] offsets,
                                   java.lang.String namespace)
        Invoked before inserting multiple elements at the given offsets.
        Note: The offsets and elements are in document order and this rule must also be followed by the filter processing.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        parentElement - The parent element that contains all the new inserted elements.
        elementNames - The element names to be inserted.
        offsets - The absolute offsets where the elements will be inserted. 0 based.
        namespace - The namespace of the new inserted elements.

      • insertMultipleFragments

        public boolean insertMultipleFragments​(AuthorDocumentFilterBypass filterBypass,
                                       AuthorElement parentElement,
                                       AuthorDocumentFragment[] fragments,
                                       int[] offsets)
        Invoked before inserting multiple fragments at the given offsets.
        Note: The offsets and fragments are in document order and this rule must also be followed by the filter processing.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        parentElement - The parent element that contains all the new inserted elements.
        fragments - The fragments to be inserted.
        offsets - The absolute offsets where the fragments will be inserted. 0 based.
        Returns:
        true if the insert operation succeed.
        Since:
        14

      • delete

        public boolean delete​(AuthorDocumentFilterBypass filterBypass,
                      int startOffset,
                      int endOffset,
                      boolean withBackspace)
        Invoked before deleting the fragment between the specified offsets from the document.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        startOffset - Start offset of the fragment, 0 based and inclusive.
        endOffset - End offset of the fragment, 0 based and inclusive.
        withBackspace - true if BACKSPACE key was used for deleting the fragment.
        Returns:
        true If the delete operation succeeded.

      • deleteNode

        public boolean deleteNode​(AuthorDocumentFilterBypass filterBypass,
                          AuthorNode node)
        Invoked before deleting the specified node from the document.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        node - The AuthorNode to delete.
        Returns:
        true if the delete node operation was successful.

      • multipleDelete

        public void multipleDelete​(AuthorDocumentFilterBypass filterBypass,
                           AuthorElement parentElement,
                           int[] startOffsets,
                           int[] endOffsets)
        Invoked before deleting the given intervals from the document.
        Note: The offsets must be in document order and the intervals must not intersect with each other. This rule must also be followed by the filter processing.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        parentElement - The element that contains all the deleted intervals.
        startOffsets - The start offset for each interval. Must be in document order. 0 based and inclusive.
        endOffsets - The end offset for each interval. Must be in document order. 0 based and inclusive.

      • renameElement

        public void renameElement​(AuthorDocumentFilterBypass filterBypass,
                          AuthorElement element,
                          java.lang.String newName,
                          java.lang.Object infoProvider)
        Invoked before renaming the given element.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        element - The AuthorElement that is renamed.
        newName - The new name for the element.
        infoProvider - Information provider used for internal processing. It must NOT be altered inside this AuthorDocumentFilter method.

      • setAttribute

        public void setAttribute​(AuthorDocumentFilterBypass filterBypass,
                         java.lang.String attributeName,
                         AttrValue value,
                         AuthorElement element)
        Invoked before setting the value of an attribute in the specified element.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        attributeName - Name of the attribute being changed.
        value - New AttrValue for the attribute. If null, the attribute is removed from the element.
        element - The AuthorElement whose attribute we are editing.

      • removeAttribute

        public void removeAttribute​(AuthorDocumentFilterBypass filterBypass,
                            java.lang.String attributeName,
                            AuthorElement element)
        Invoked before removing an attribute from the specified element.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        attributeName - Name of the attribute to remove.
        element - The AuthorElement whose attribute will be removed.

      • split

        public boolean split​(AuthorDocumentFilterBypass filterBypass,
                     AuthorNode toSplit,
                     int splitOffset)
        Invoked before splitting the specified node into two similar nodes. The node to split is the first ancestor block level node containing the splitOffset. The attributes of the splitted node will also be copied excepting the unique ones. The unique attributes are identified by the UniqueAttributesRecognizer.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        toSplit - The AuthorNode to split.
        splitOffset - The split offset. The given offset is greater or equal to 1 and less than the current document length.
        Returns:
        true if the node was split.

      • surroundWithNode

        public void surroundWithNode​(AuthorDocumentFilterBypass filterBypass,
                             AuthorNode node,
                             int startOffset,
                             int endOffset,
                             boolean leftToRight)
        Invoked before surrounding the fragment between the specified offset with the specified node. The fragment between the start and end offsets will become the node actual content.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        node - The AuthorNode that will surround the fragment.
        startOffset - Start offset of the surrounded fragment. 0 based and inclusive.
        endOffset - End offset of the surrounded fragment. 0 based and inclusive.
        leftToRight - true if after the operation the selection in the author page is done from the left to the right.

      • surroundInFragment

        public void surroundInFragment​(AuthorDocumentFilterBypass filterBypass,
                               java.lang.String xmlFragment,
                               int startOffset,
                               int endOffset)
                        throws AuthorOperationException
        Invoked before surrounding the content between the given offsets with the xmlFragment. If endOffset < startOffset the xmlFragment will be inserted at startOffset.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        xmlFragment - The XML fragment which will surround the given interval. The first leaf node of the XML fragment will be the parent of the surrounded content.
        startOffset - The start offset of the content to be surrounded, 0 based and inclusive.
        endOffset - The end offset of the content to be surrounded, 0 based and inclusive.
        Throws:
        AuthorOperationException - If the content between start and end offset could not be surrounded.

      • surroundInFragment

        public void surroundInFragment​(AuthorDocumentFilterBypass filterBypass,
                               AuthorDocumentFragment xmlFragment,
                               int startOffset,
                               int endOffset)
                        throws AuthorOperationException
        Invoked before surrounding the content between the given offsets with the xmlFragment. If endOffset < startOffset the xmlFragment will be inserted at startOffset.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        xmlFragment - The XML fragment which will surround the given interval. The first leaf node of the XML fragment will be the parent of the surrounded content.
        startOffset - The start offset of the content to be surrounded, 0 based and inclusive.
        endOffset - The end offset of the content to be surrounded, 0 based and inclusive.
        Throws:
        AuthorOperationException
        Since:
        12.1

      • surroundInText

        public void surroundInText​(AuthorDocumentFilterBypass filterBypass,
                           java.lang.String header,
                           java.lang.String footer,
                           int startOffset,
                           int endOffset)
                    throws AuthorOperationException
        Invoked before surrounding the content between the given offsets with plain text fragments(without XML parsing). The method inserts the header at startOffset and the footer at endOffset.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        header - The header to be inserted before the surrounded text.
        footer - The footer to be inserted after the surrounded text.
        startOffset - The start offset of the text to be surrounded, 0 based and inclusive.
        endOffset - The end offset of the text to be surrounded, 0 based and inclusive.
        Throws:
        AuthorOperationException - If the operation failed.

      • setDoctype

        public void setDoctype​(AuthorDocumentFilterBypass filterBypass,
                       AuthorDocumentType docType)
        Invoked before setting a new internal document type to the Author content.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        docType - The document type information to set.

      • setMultipleDistinctAttributes

        public void setMultipleDistinctAttributes​(AuthorDocumentFilterBypass filterBypass,
                                          int parentElementStartOffset,
                                          int[] elementOffsets,
                                          java.util.List<java.util.Map<java.lang.String,​AttrValue>> attributes)
        Sets the value of the given attribute in the specified elements. Attributes set in this manner will be subject to undo/redo.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        parentElementStartOffset - The start offset of the parent element.
        elementOffsets - The start offset for each element.
        attributes - The list with attributes. Every attribute name is mapped to an AttrValue object. If the value is null, the attribute will be removed.

      • setMultipleAttributes

        public void setMultipleAttributes​(AuthorDocumentFilterBypass filterBypass,
                                  int parentElementStartOffset,
                                  int[] elementOffsets,
                                  java.util.Map<java.lang.String,​AttrValue> attributes)
        Sets the value of the given attribute in the specified elements. Attributes set in this manner will be subject to undo/redo.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        parentElementStartOffset - The start offset of the parent element.
        elementOffsets - The start offset for each element.
        attributes - The list with attributes. Every attribute name is mapped to an AttrValue object. If the value is null, the attribute will be removed.

      • removeMarker

        public boolean removeMarker​(AuthorDocumentFilterBypass filterBypass,
                            AuthorPersistentHighlight marker)
        Remove a persistent marker.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        marker - The persistent marker to remove.
        Returns:
        true if the marker was removed
        Since:
        22

      • addCommentMarker

        public AuthorPersistentHighlight addCommentMarker​(AuthorDocumentFilterBypass filterBypass,
                                                  int startOffset,
                                                  int endOffset,
                                                  java.lang.String comment,
                                                  java.lang.String parentID)
        Add a comment marker for the given interval.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        startOffset - Start offset of marker
        endOffset - End offset of marker
        comment - The comment to be added.
        parentID - The comment parent id (not null for replies).
        Returns:
        The added comment highlight if the comment was added or null.
        Since:
        22

      • addPersistentMarker

        public AuthorPersistentHighlight addPersistentMarker​(AuthorDocumentFilterBypass filterBypass,
                                                     AuthorPersistentHighlight.PersistentHighlightType type,
                                                     int startOffset,
                                                     int endOffset,
                                                     java.util.Map<java.lang.String,​java.lang.String> properties)
        Add a comment marker for the given interval.

        Subclasses that want to conditionally modify the default processing should override this and only call super implementation as necessary, or call directly into the AuthorDocumentFilterBypass as necessary.

        Parameters:
        filterBypass - The document filter bypass used for executing operations directly, without additional filtering.
        type - The persistent marker type (comment or custom)
        startOffset - Start offset of marker
        endOffset - End offset of marker
        properties - The comment properties. See AuthorPersistentHighlightConstants for properties that are meaningful in Oxygen.
        Returns:
        The added comment highlight if the comment was added or null.
        Since:
        23