Configuring an Extensions Bundle
All extensions that are provided by Oxygen XML Editor are includes in a single bundle.
Note
The extensions bundle is represented by the ro.sync.ecss.extensions.api.ExtensionsBundle class. The
               provided implementation of the ExtensionsBundle is instantiated when the
               rules of the Document Type Association defined for the custom framework matches
               a document opened in the editor. Therefore, references to objects that need to be
               persistent
               throughout the application running session must not be kept in the bundle because
               the next
               detection event can result in creating another ExtensionsBundle
               instance.
            
To configure an extensions bundle, follow this procedure:
- Create a new Java project in your IDE. Create a libfolder in the Java project folder and copy in it theoxygen.jarfile from the[OXYGEN_INSTALL_DIR]/libfolder.
- Create the class (for example,
                  simple.documentation.framework.SDFExtensionsBundle) to extend the abstract classro.sync.ecss.extensions.api.ExtensionsBundle.For example:public class SDFExtensionsBundle extends ExtensionsBundle {
- A Document Type ID and a short description should be defined first by
                  implementing the methods getDocumentTypeIDandgetDescription. The Document Type ID is used to uniquely identify the current framework. Such an ID must be provided especially if options related to the framework need to be persistently stored and retrieved between sessions.For example:public String getDocumentTypeID() { return "Simple.Document.Framework.document.type"; } public String getDescription() { return "A custom extensions bundle used for the Simple Document" + "Framework document type"; }
- To be notified about the activation of the custom Author Extension in relation
                  with an opened document, ro.sync.ecss.extensions.api.AuthorExtensionStateListenershould be implemented. The activation and deactivation events received by this listener should be used to perform custom initializations and to register or remove listeners such asro.sync.ecss.extensions.api.AuthorListener,ro.sync.ecss.extensions.api.AuthorMouseListener, orro.sync.ecss.extensions.api.AuthorCaretListener. The custom Author Extension state listener should be provided by implementing thecreateAuthorExtensionStateListenermethod.For example:public AuthorExtensionStateListener createAuthorExtensionStateListener() { return new SDFAuthorExtensionStateListener(); }The AuthorExtensionStateListeneris instantiated and notified about the activation of the framework when the rules of the Document Type Association match a document opened in the Author editing mode. The listener is notified about the deactivation when another framework is activated for the same document, the user switches to another mode or the editor is closed. A complete description and implementation ofro.sync.ecss.extensions.api.AuthorExtensionStateListenercan be found in Implementing an Author Extension State Listener.If Schema Aware mode is active in Oxygen XML Editor, all actions that can generate invalid content will be redirected toward the ro.sync.ecss.extensions.api.AuthorSchemaAwareEditingHandler. The handler can resolve a specific case, let the default implementation take place, or reject the edit entirely by throwing anro.sync.ecss.extensions.api.InvalidEditException. The actions that are forwarded to this handler include typing, delete, or paste.See Implementing a Schema-Aware Editing Handler Adapter for more details about this handler. 
- Customizations of the content completion proposals are permitted by creating a schema
                  manager filter extension. The interface that declares the methods used for content
                  completion proposals filtering is ro.sync.contentcompletion.xml.SchemaManagerFilter. The filter can be applied on elements, attributes, or on their values. ThecreateSchemaManagerFiltermethod is responsible for creating the content completion filter. A newSchemaManagerFilterwill be created each time a document matches the rules defined by the Document Type Association that contains the filter declaration.For example:public SchemaManagerFilter createSchemaManagerFilter() { return new SDFSchemaManagerFilter(); }A detailed presentation of the schema manager filter can be found in the Configuring a Content Completion Handler section. 
- The Author mode supports link-based navigation between documents
                  and document sections. Therefore, if the document contains elements defined as links
                  to
                  other elements (for example, links based on the id attributes), the extension
                  should provide the means to find the referenced content. To do this, an implementation
                  of
                  the ro.sync.ecss.extensions.api.link.ElementLocatorProviderinterface should be returned by thecreateElementLocatorProvidermethod. Each time an element pointed by a link needs to be located, the method is invoked.For example:public ElementLocatorProvider createElementLocatorProvider() { return new DefaultElementLocatorProvider(); }For more information on how to implement an element locator provider, see the Configuring a Link Target Element Finder section. 
- The drag and drop functionality can be extended by implementing the ro.sync.exml.editor.xmleditor.pageauthor.AuthorDnDListenerinterface. Relevant methods from the listener are invoked when the mouse is dragged, moved over, or exits the Author editing mode, when the drop action changes, and when the drop occurs. Each method receives theDropTargetEventcontaining information about the drag and drop operation. The drag and drop extensions are available in Author mode for both Oxygen XML Editor Eclipse plugin and standalone application. The Text mode corresponding listener is available only for Oxygen XML Editor Eclipse plugin. The methods corresponding to each implementation are:createAuthorAWTDndListener,createTextSWTDndListener, andcreateAuthorSWTDndListener.public AuthorDnDListener createAuthorAWTDndListener() { return new SDFAuthorDndListener(); }For more details about the Author mode drag and drop listeners, see the Configuring a custom Drag and Drop Listener section. 
- Another extension that can be included in the bundle is the reference resolver. In
                  our
                  example, the references are represented by the ref element and the attribute
                  indicating the referenced resource is location. To be able to obtain the content of
                  the referenced resources you will have to implement a Java extension class that implements
                  ro.sync.ecss.extensions.api.AuthorReferenceResolver. The method responsible for creating the custom references resolver iscreateAuthorReferenceResolver. The method is called each time a document opened in an Author editing mode matches the Document Type Association where the extensions bundle is defined. The instantiated references resolver object is kept and used until another extensions bundle corresponding to another Document Type is activated as result of the detection process.For example:public AuthorReferenceResolver createAuthorReferenceResolver() { return new ReferencesResolver(); }A more detailed description of the references resolver can be found in the Configuring a References Resolver section. 
- To be able to dynamically customize the default CSS styles for a certain ro.sync.ecss.extensions.api.node.AuthorNode, an implementation ofro.sync.ecss.extensions.api.StylesFiltercan be provided. The extensions bundle method responsible for creating theStylesFilteriscreateAuthorStylesFilter. The method is called each time a document opened in an Author editing mode matches the Document Type Association where the extensions bundle is defined. The instantiated filter object is kept and used until another extensions bundle corresponding to another Document Type is activated as a result of the detection process.For example:public StylesFilter createAuthorStylesFilter() { return new SDFStylesFilter(); }See the Configuring CSS Styles Filter section for more details about the styles filter extension. 
- To edit data in custom tabular format, implementations of the ro.sync.ecss.extensions.api.AuthorTableCellSpanProviderandthe ro.sync.ecss.extensions.api.AuthorTableColumnWidthProviderinterfaces should be provided. The two methods from theExtensionsBundlespecifying these two extension points arecreateAuthorTableCellSpanProviderandcreateAuthorTableColumnWidthProvider.For example:public AuthorTableCellSpanProvider createAuthorTableCellSpanProvider() { return new TableCellSpanProvider(); } public AuthorTableColumnWidthProvider createAuthorTableColumnWidthProvider() { return new TableColumnWidthProvider(); }The two table information providers are not reused for different tables. The methods are called for each table in the document so new instances should be provided every time. Read more about the cell span and column width information providers in Configuring a Table Cell Span Provider and Configuring a Table Column Width Provider sections. If the functionality related to one of the previous extension point does not need to be modified, then the developed ro.sync.ecss.extensions.api.ExtensionsBundleshould not override the corresponding method and leave the default base implementation to return null.
- An XML vocabulary can contain links to various areas of a document. If the document
                  contains elements defined as links, you can choose to present a more relevant text
                  description for each link. To do this, an implementation of the ro.sync.ecss.extensions.api.link.LinkTextResolverinterface should be returned by thecreateLinkTextResolvermethod. This implementation is used each time theoxy_link-text() functionis encountered in the CSS styles associated with an element.For example:public LinkTextResolver createLinkTextResolver() { return new DitaLinkTextResolver(); }Oxygen XML Editor offers built-in implementations for DITA and DocBook: ro.sync.ecss.extensions.dita.link.DitaLinkTextResolverandro.sync.ecss.extensions.docbook.link.DocbookLinkTextResolverrespectively.
- Pack the compiled class into a jar file.
- Copy the jar file into your custom framework directory (for example,
                  frameworks/sdf).
- Add the jar file to the class path. To do this, open the
                        Preferences dialog box , go to
                  Document Type Association, select the document type (for example,
                  SDF), press the Edit button, select the
                  Classpath tab, and press the 
                      Add button . In the
                  displayed dialog box, enter the location of the jar file relative to the Oxygen XML Editor Add button . In the
                  displayed dialog box, enter the location of the jar file relative to the Oxygen XML Editorframeworksfolder.
- Register the Java class by going to the Extensions tab. Press
                  the Choose button and select the name of the class (for example,
                  SDFExtensionsBundle).NoteThe complete source code for the examples can be found in the Simple Documentation Framework project, included in the oxygen-sample-framework module of the Oxygen SDK , available as a Maven archetype on the Oxygen XML Editor website.
