<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 we 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 we 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.
We assume 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 Author . Otherwise the classes may not be loaded by the Java virtual machine. For example if you run <oXygen/> XML Author 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 our
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 our Java implementation we
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 we 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 our 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.
We assume the icon files
Image16.gif
for the menu item and
Image20.gif
for the toolbar 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
We will use: Ctrl+Shift+i.
Now let's set up the operation.
We 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, we'll use our Java operation
we 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.