You can add extensions to your Document Type Association using the Extensions tab from the Document Type dialog.
Starting with <oXygen/> 10.3 version a single bundle was introduced acting as a provider for all other extensions. The individual extensions can still be set 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
directory in the Java
project directory and copy in it the oxygen.jar
file from the {oXygen_installation_directory}/lib
directory.
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 page. The
listener is notified about the deactivation when another
framework is activated for the same document, the user
switches to another page 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.
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 <oXygen/> Author supports link based navigation between
documents and document sections. Therefor, 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 page, 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 page for both <oXygen/>
Eclipse plugin and standalone application. The Text page
corresponding listener is available only for <oXygen/> 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 re
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 we 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 page 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 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 page 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
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 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 button and select from the
displayed dialog the name of the class:
SDFExtensionsBundle
.
The complete source code of the SDFExtensionsBundle
implementation is found in the Example Files Listings, the Java Files
section.