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 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.
  2. 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.";
    }
    Note: The complete source code can be found in the Simple Documentation Framework project, included in the Oxygen Author SDK zip available for download on the Oxygen XML Author website.
    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'/>
  3. 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>
    
  4. Copy the sdf.jar file into the frameworks / sdf folder.
  5. Add the sdf.jar to the Author class path. To do this, open the Options > Preferences > Document Type Association dialog, select SDF and press the Edit button.
  6. 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.
  7. 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.
  8. 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.
  9. Now let's set up the operation. You want to add images only if the current element is a section, book or article.
    • Set the value of XPath expression to
      local-name()='section' or local-name()='book' 
       or local-name()='article'
    • Set the Invoke operation field to simple.documentation.framework.InsertImageOperation.

    Selecting the Operation

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