<oXygen/> Author has a built-in set of operations covering the insertion of text and XML fragments (see the Author Default Operations) and the execution of XPath expressions on the current document edited in Author mode. However, there are situations in which you need to extend this set. For instance if you need to enter an element whose attributes should be edited by the user through a graphical user interface. Or the users must send the selected element content or even the whole document to a server, for some kind of processing or the content authors must extract pieces of information from a server and insert it directly into the edited XML document. Or you need to apply an XPath expression on the current Author document and process the nodes of the result nodeset.
In the following sections you are presenting the Java programming interface (API) available to the developers. You will need the Oxygen Author SDK available on the <oXygen/> website which includes the source code of the Author operations in the predefined document types and the full documentation in Javadoc format of the public API available for the developer of Author custom actions.
The next Java examples are making use of AWT classes. If you are developing extensions for the <oXygen/> XML Editor plugin for Eclipse you will have to use their SWT counterparts.
It is assumed you already read the Configuring Actions, Menus, Toolbar section and you are familiar with the <oXygen/> Author customization. You may find the XML schema, CSS and XML sample in the Example Files Listings.
![]() | Warning |
---|---|
Make sure the Java classes of your custom Author operations are compiled with the same Java version that is used by <oXygen/>XML Editor . Otherwise the classes may not be loaded by the Java virtual machine. For example if you run <oXygen/>XML Editor with a Java 1.5 virtual machine but the Java classes of your custom Author operations are compiled with a Java 1.6 virtual machine then the custom operations cannot be loaded and used by the Java 1.5 virtual machine. |
Let's start adding functionality for inserting images in the Simple Documentation Framework (shortly SDF). The
images are represented by the image
element. The location of the image
file is represented by the value of the href
attribute. In the Java
implementation you will show a dialog with a text field, in which the user can enter a
full URL, or he can browse for a local file.
Create a new Java project, in your IDE.
Create the directory lib
in the Java project directory
and copy in it the oxygen.jar
file from the
{oXygen_installation_directory}/lib
directory. The
oxygen.jar
contains the Java interfaces you have to
implement and the API needed to access the Author features.
Create the class
simple.documentation.framework.InsertImageOperation
. This
class must implement the
ro.sync.ecss.extensions.api.AuthorOperation
interface.
The interface defines three methods: doOperation
,
getArguments
and
getDescription
.
The doOperation
method is invoked when the action
is performed either by pressing the toolbar button, selecting the menu item or
through the shortcut. It takes as arguments an object of type
AuthorAccess
and a map or argument names and
values.
The getArguments
method is used by <oXygen/> when the
action is configured, it returns the list of arguments (name and type) that
are accepted by the operation.
The getDescription
method is also used by <oXygen/>
when the operation is configured and its return value describes what the
operation does.
Here is the implementation of these three methods.
/** * Performs the operation. */ public void doOperation( AuthorAccess authorAccess, ArgumentsMap arguments) throws IllegalArgumentException, AuthorOperationException { JFrame oxygenFrame = (JFrame) authorAccess.getParentFrame(); String href = displayURLDialog(oxygenFrame); if (href.length() != 0) { // Creates the image XML fragment. String imageFragment = "<image xmlns='http://www.oxygenxml.com/sample/documentation' href='" + href + "'/>"; // Inserts this fragment at the caret position. int caretPosition = authorAccess.getCaretOffset(); authorAccess.insertXMLFragment(imageFragment, caretPosition); } } /** * Has no arguments. * * @return null. */ public ArgumentDescriptor[] getArguments() { return null; } /** * @return A description of the operation. */ public String getDescription() { return "Inserts an image element. Asks the user for a URL reference."; }
The complete source code of this operation is found in the Example Files Listings, the Java Files section.
![]() | Important |
---|---|
Make sure you always specify the namespace of the inserted fragments. |
Package the compiled class into a jar file. An example of an ANT script that
packages the classes
directory content into a jar archive
named sdf.jar
is listed below:
<?xml version="1.0" encoding="UTF-8"?> <project name="project" default="dist"> <target name="dist"> <jar destfile="sdf.jar" basedir="classes"> <fileset dir="classes"> <include name="**/*"/> </fileset> </jar> </target> </project>
Copy the sdf.jar
file into the
frameworks/sdf
directory.
Add the sdf.jar
to the Author class path. To do this,
Open the options Document Type Dialog, select SDF
and press the button.
Select the Classpath tab in the lower part of the dialog.
Press the frameworks
directory:
Let's create now the action which will use the defined operation. Click on the Actions label.
The icon files are
Image16.gif
for the menu item and
Image20.gif
for the toolbar and are already available. Place
these files in the frameworks/sdf
directory.
Define the action properties:
An unique identifier for the action. Use insert_image.
The name of the action. Use Insert image.
Use the i letter.
Enter the text Inserts an image.
Enter here: ${frameworks}/sdf/Image20.gif
Enter here: ${frameworks}/sdf/Image16.gif
You will use: Ctrl+Shift+i.
Now let's set up the operation.
You are adding images only if the current element is a section
,
book
or article
.
Set the value to:
local-name()='section' or local-name='book' or local-name='article'
In this case, you will use the Java operation you defined earlier. Press
the simple.documentation.framework.InsertImageOperation
.
This operation has no arguments.
Add the action to the toolbar, using the Toolbar panel.
To test the action, you can open the sdf.xml
sample, then
place the caret inside a section
between two para
elements for instance. Press the button associated with the action from the toolbar.
In the dialog select an image URL and press . The image is
inserted into the document.