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.
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.