Java API - Extending Author Functionality through Java

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

 Example 1. Step by Step Example. Simple Use of a Dialog from an Author Operation.

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.

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

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

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

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

    3. 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]Important

    Make sure you always specify the namespace of the inserted fragments.

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

  4. Copy the sdf.jar file into the frameworks/sdf directory.

  5. Add the sdf.jar to the Author class path. To do this, Open the options Document Type Dialog, select SDF and press the Edit button.

    Select the Classpath tab in the lower part of the dialog.

    Press the Add button . In the displayed dialog enter the location of the jar file, relative to the <oXygen/> frameworks directory:

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

    ID

    An unique identifier for the action. Use insert_image.

    Name

    The name of the action. Use Insert image.

    Menu access key

    Use the i letter.

    Description

    Enter the text Inserts an image.

    Toolbar icon

    Enter here: ${frameworks}/sdf/Image20.gif

    Menu icon

    Enter here: ${frameworks}/sdf/Image16.gif

    Shortcut key

    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.

    XPath expression

    Set the value to:

    local-name()='section' or local-name='book' 
     or local-name='article'
    Invoke operation

    In this case, you will use the Java operation you defined earlier. Press the Choose button, then select simple.documentation.framework.InsertImageOperation.

     

    Figure 8.16. Selecting the Operation

    Selecting the Operation

    This operation has no arguments.

  7. 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 Ok. The image is inserted into the document.