Implementing Custom Form Controls

If the built-in form controls are not sufficient for your needs, you can implement custom form controls in Java.

Custom Form Controls Implementation

You can specify custom form controls using the following properties:

rendererClassName - The name of the class that draws the edited value. It must be an implementation of ro.sync.ecss.extensions.api.editor.InplaceRenderer. The renderer has to be a SWING implementation and can be used both in the standalone and Eclipse distributions.
swingEditorClassName - You can use this property for the standalone (Swing-based) distribution to specify the name of the class used for editing. It is a Swing implementation of ro.sync.ecss.extensions.api.editor.InplaceEditor.
swtEditorClassName - You can use this property for the Eclipse plugin distribution to specify the name of the class used for editing. It is a SWT implementation of the ro.sync.ecss.extensions.api.editor.InplaceEditor.
Note: If the custom form control is intended to work in the Oxygen XML Author standalone distribution, the declaration of swtEditorClassName is not required. The renderer (the class that draws the value) has different properties from the editor (the class that edits the value) because you can present a value in one way and edit it in another.
classpath - You can use this property to specify the location of the classes used for a custom form control. The value of the classpath property is an enumeration of URLs separated by comma.
edit - If your form control edits the value of an attribute or the text value of an element, you can use the @attribute_name and #text predefined values and Oxygen XML Author will perform the commit logic by itself. You can use the custom value to perform the commit logic yourself.
saHeavyFormControlClassName - This type of form control is effectively present at all times at its allocated bounds. This is useful if you need a form control that renders dynamic or interactive SVG documents (for example, if you have an SVG document that displays tooltips when hovering over certain areas). It is also helpful if you want to use JavaFX, since JavaFX-based form controls are not compatible with the classic form control architecture.

The value of this property is a class name that must implement the ro.sync.ecss.extensions.api.editor.InplaceHeavyEditor method. The JAR that contains this implementation can either be added in the Classpath tab in the Document Type Configuration dialog box for your particular framework or specified with the classpath property.

Example: Java Code

The following is a sample Java code for implementing a custom combo box form control that inserts an XML element in the content when the editing stops:

public class ComboBoxEditor  extends AbstractInplaceEditor {
  /**
   * @see ro.sync.ecss.extensions.api.editor.InplaceEditor#stopEditing()
   */
  @Override
   public void stopEditing() {
     Runnable customCommit =  new Runnable() {
      @Override
       public void run() {
        AuthorDocumentController documentController = 
            context.getAuthorAccess().getDocumentController();
        documentController.insertXMLFragment( "<custom/>", offset);
      }
    };
    EditingEvent event =  new EditingEvent(customCommit,  true);
    fireEditingStopped(event);
  }

The custom form controls can use any of the predefined properties of the built-in form controls, as well as specified custom properties.

Example: CSS

The following is an example of how to specify a custom form control in the CSS:

myElement {
    content: oxy_editor(
        rendererClassName, "com.custom.editors.CustomRenderer",
        swingEditorClassName, "com.custom.editors.SwingCustomEditor",
        swtEditorClassName, "com.custom.editors.SwtCustomEditor",
        edit, "@my_attr",
        customProperty1, "customValue1",
        customProperty2, "customValue2"
    )
}

How to Implement Custom Form Controls

To implement a custom form control, follow these steps:

Download the Oxygen XML Author SDK at: https://www.oxygenxml.com/oxygen_sdk.html.
Implement the custom form control by extending ro.sync.ecss.extensions.api.editor.InplaceEditorRendererAdapter. You could also use ro.sync.ecss.extensions.api.editor.AbstractInplaceEditor, which offers some default implementations and listeners management.
Pack the previous implementation in a Java JAR library.
Copy the JAR library to the [OXYGEN_INSTALL_DIR]/frameworks/[FRAMEWORK_DIR] directory.
In Oxygen XML Author, open the Preferences dialog box (Options > Preferences), go to Document Type Association, edit the appropriate framework, and add the JAR library in the Classpath tab.
Specify the custom form control in your CSS, as described above.

Tip: To see more detailed examples and more information about how form controls work in Oxygen XML Author, see the sample files in the following directory: [OXYGEN_INSTALL_DIR]/samples/form-controls.

Resources

For more information about form controls, watch our video demonstration: