oXygen Author has a built-in set of operations covering the insertion of text and XML fragments, see the Author Default Operations. 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.
In the following sections we are presenting the Java programming interface (API) available to the developers. 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 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 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.