Starting with
Oxygen XML Author plugin
10.3 version a single bundle was introduced acting as a provider for all other extensions.
The individual extensions can still be set and if present they take precedence over the
single provider, but this practice is being discouraged and the single provider should be
used instead.
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 match a document
opened in the editor. Therefor references to objects which 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.
-
Create a new Java project, in your IDE. Create the lib folder in
the Java project folder and copy in it the oxygen.jar file from the
{oXygen_installation_directory}/lib folder.
-
Create the class simple.documentation.framework.SDFExtensionsBundle
which must extend the abstract class
ro.sync.ecss.extensions.api.ExtensionsBundle.
public class SDFExtensionsBundle extends ExtensionsBundle {
-
A Document Type ID and a short description should be defined first by
implementing the methods getDocumentTypeID and
getDescription. 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.
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";
}
-
In order to be notified about the activation of the custom Author extension in relation
with an opened document an ro.sync.ecss.extensions.api.AuthorExtensionStateListener
should be implemented. The activation and deactivation events received by
this listener should be used to perform custom initializations and to register / remove
listeners like ro.sync.ecss.extensions.api.AuthorListener, ro.sync.ecss.extensions.api.AuthorMouseListener or ro.sync.ecss.extensions.api.AuthorCaretListener. The custom
author extension state listener should be provided by implementing the method
createAuthorExtensionStateListener.
public AuthorExtensionStateListener createAuthorExtensionStateListener() {
return new SDFAuthorExtensionStateListener();
}
The AuthorExtensionStateListener is instantiated and notified about
the activation of the framework when the rules of the Document Type Association match a
document opened in the Author editor 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 of an
ro.sync.ecss.extensions.api.AuthorExtensionStateListener can be
found in the Implementing
an Author Extension State Listener.
If Schema Aware mode is active in Oxygen, all actions that can generate invalid content
will be redirected toward the ro.sync.ecss.extensions.api.AuthorSchemaAwareEditingHandler.
The handler can either resolve a specific case, let the default implementation take
place or reject the edit entirely by throwing an ro.sync.ecss.extensions.api.InvalidEditException. The
actions that are forwarded to this handler include typing, delete or paste.
See the Implementing
an Author Schema Aware Editing Handler section 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. Responsible for creating
the content completion filter is the method createSchemaManagerFilter.
A new SchemaManagerFilter will be created each time a document matches
the rules defined by the Document Type Association which contains the filter
declaration.
public SchemaManagerFilter createSchemaManagerFilter() {
return new SDFSchemaManagerFilter();
}
A detailed presentation of the schema manager filter can be found in Configuring a Content
completion handler section.
-
The Author 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 referred content. To do this an implementation of the ro.sync.ecss.extensions.api.link.ElementLocatorProvider
interface should be returned by the createElementLocatorProvider
method. Each time an element pointed by a link needs to be located the method is
invoked.
public ElementLocatorProvider createElementLocatorProvider() {
return new DefaultElementLocatorProvider();
}
The section that explains how to implement an element locator provider is Configuring a Link target
element finder.
-
The drag and drop functionality can be extended by implementing the ro.sync.exml.editor.xmleditor.pageauthor.AuthorDnDListener
interface. Relevant methods from the listener are invoked when the mouse is dragged, moved
over, or exits the Author editor mode, when the drop action changes, and when the drop
occurs. Each method receives the DropTargetEvent containing information
about the drag and drop operation. The drag and drop extensions are available on Author
mode for both
Oxygen XML Author plugin
Eclipse plugin and standalone application. The Text mode corresponding listener is
available only for
Oxygen XML Author plugin
Eclipse
plugin. The methods corresponding to each implementation are:
createAuthorAWTDndListener,
createTextSWTDndListener and
createAuthorSWTDndListener.
public AuthorDnDListener createAuthorAWTDndListener() {
return new SDFAuthorDndListener();
}
For more details about the Author drag and drop listeners see the Configuring a custom Drag and Drop
listener section.
-
Another extension which can be included in the bundle is the reference resolver. In our
case the references are represented by the ref element and the attribute indicating
the referred resource is location. To be able to obtain the content of the referred
resources you will have to implement a Java extension class which implements the ro.sync.ecss.extensions.api.AuthorReferenceResolver. The
method responsible for creating the custom references resolver is
createAuthorReferenceResolver. The method is called each time a
document opened in an Author editor 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.
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 of the ro.sync.ecss.extensions.api.StylesFilter can be provided.
The extensions bundle method responsible for creating the StylesFilter is
createAuthorStylesFilter. The method is called each time a document
opened in an Author editor 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.
public StylesFilter createAuthorStylesFilter() {
return new SDFStylesFilter();
}
See the Configuring CSS styles
filter section for more details about the styles filter extension.
-
In order to edit data in custom tabular format implementations of the ro.sync.ecss.extensions.api.AuthorTableCellSpanProvider and
the
ro.sync.ecss.extensions.api.AuthorTableColumnWidthProvider interfaces
should be provided. The two methods from the ExtensionsBundle specifying
these two extension points are createAuthorTableCellSpanProvider and
createAuthorTableColumnWidthProvider.
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.ExtensionsBundle should not
override the corresponding method and leave the default base implementation to return
null.
-
Package the compiled class into a jar file.
-
Copy the jar file into the frameworks / sdf directory.
-
Add the jar file to the Author class path.
-
Register the Java class by clicking on the Extensions tab. Press
the Choose button and select from the displayed dialog the name of
the class: SDFExtensionsBundle.