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 of choice. Create the lib
folder in the project folder. Copy the oxygen.jar file from the
{oXygen_installation_directory}/lib folder into the newly created
lib folder. oxygen.jar contains the Java
interfaces you have to implement and the API needed to access the Author features.
-
Create the simple.documentation.framework.InsertImageOperation class
that implements the ro.sync.ecss.extensions.api.AuthorOperation interface. This
interface defines three methods: doOperation,
getArguments and getDescription
A short description of these methods follows:
- The doOperation method is invoked when the action is performed
either by pressing the toolbar button, by selecting the menu item or by pressing the
shortcut key. The arguments taken by this methods can be one of the following
combinations:
- The getArguments method is used by
Oxygen XML Author
when the
action is configured. It returns the list of arguments (name and type) that are
accepted by the operation.
- The getDescription method is used by
Oxygen XML Author
when the
operation is configured. It returns a description of the operation.
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.";
}
Important:
Make sure you always specify the namespace of the inserted fragments.
<image xmlns='http://www.oxygenxml.com/sample/documentation'
href='path/to/image.png'/>
-
Package the compiled class into a jar file. An example of an ANT script that packages
the classes folder 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 folder.
-
Add the sdf.jar to the Author class path. To do this, open the dialog, select SDF and press the Edit button.
-
Select the Classpath tab in the lower part of the dialog and
press the
Add button . In the displayed dialog
enter the location of the jar file, relative to the
Oxygen XML Author
frameworks folder.
-
Let's create now the action which will use the defined operation. Click on the
Actions label. Copy the icon files for the menu item and for the
toolbar in the frameworks / sdf folder.
-
Define the action's properties:
- Set ID to insert_image.
- Set Name to Insert image.
- Set Menu access key to letter i.
- Set Toolbar action to ${frameworks}/sdf/toolbarImage.png.
- Set Menu icon to ${frameworks}/sdf/menuImage.png.
- Set Shortcut key to Ctrl+Shift+i.
-
Now let's set up the operation. You want to add images only if the current element is a
section, book or article.
Selecting the Operation
-
Add the action to the toolbar, using the Toolbar panel.
To test the action, you can open the sdf_sample.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 OK. The image is inserted into the document.