Chapter 7. Writing a custom attribute editor

Table of Contents

1. What is a custom attribute editor?
2. Compiling and running the code sample
3. A custom editor for the bgcolor attribute

1. What is a custom attribute editor?

A custom attribute editor extends the Attributes tool. There are two kinds of such extensions:

  1. An extension which returns the list of all possible values for a given attribute. Example:

    <attributeEditor attribute="f:remove" elementMatches="f:filter"
      xmlns:f="urn:namespace:filter">
      <list>
        <item>red</item>
        <item>green</item>
        <item>blue</item>
      </list>
    </attributeEditor>
  2. An extension which creates a modal dialog box allowing to edit the value of a given attribute. This dialog box is passed the initial attribute value (or the empty string if the attribute has not yet been specified). The dialog box is then expected to return a possibly modified value for this attribute. XHTML example described in this tutorial:

    <attributeEditor attribute="bgcolor" 
      elementMatches="html:table|html:tr|html:th|html:td|html:body"
      xmlns:html="http://www.w3.org/1999/xhtml">
      <class>HexColorChooser</class>
    </attributeEditor>

In this tutorial, we'll only explain how to write the second kind of extension.

The Attributes tool invokes such extension as follows:

  1. The Value field which supports auto-completion will display the items of the list.

  2. When you click the Edit button or right-click on an attribute, this displays a popup menu. The first entry of this menu is also called Edit and displays a dialog box allowing to edit the attribute more comfortably than with the Value field. The dialog box displayed in this case comes from the attributeEditor configuration element.

2. Compiling and running the code sample

The code sample used in this tutorial is an editor for the bgcolor XHTML attribute. This attribute is defined by the XHTML 1.0 Transitional DTD for the following elements: body, table, tr, th, td. The modal dialog box displayed by this attribute editor is a standard javax.swing.JColorChooser.

Compile this attribute editor by executing ant (see build.xml) in samples/color_chooser/. The build creates colorchooser.jar. Then test the attribute editor by proceeding as following:

  1. Copy colorchooser.incl and colorchooser.jar to XXE_install_directory/addon/config/xhtml/.

  2. Include colorchooser.incl in the XXE configuration file for XHTML which is XXE_install_directory/addon/config/xhtml/xhtml_loose.xxe.

    How to deploy a custom attribute editor is detailed in Section 1, “attributeEditor” in XMLmind XML Editor - Configuration and Deployment.

  3. Restart XXE.

  4. Clear the Quick Start cache (OptionsPreferences, Advanced|Cached Data section in XMLmind XML Editor - Online Help), then restart XXE one more time. If you forget to do that, XXE will fail to see your extension.

  5. Open XXE_install_directory/demo/spreadsheet-demo.xhtml and select any element having a bgcolor attribute, for example, the table itself.

  6. Use the Attributes tool to edit the bgcolor attribute. Right-click on bgcolor or select it and then click the Edit button. Then select the Edit item from the popup menu. Doing this will display the color chooser dialog box.

3. A custom editor for the bgcolor attribute

A custom attribute editor implements interface SetAttribute.EditorFactory which is a factory class creating modal dialog boxes.

public class HexColorChooser implements SetAttribute.EditorFactory {
    public SetAttribute.Editor createEditor(Component parentComponent, 
                                            Element element, Name attributeName,
                                            DataType attributeType) {
        return new Chooser(parentComponent,
                           dialogTitle(element, attributeName));
    }
    ...

The above method is passed information identifying the attribute to be edited: element, attributeName, attributeType.

The modal dialog box created and returned by the above methods must implement interface SetAttribute.Editor.

private static class Chooser implements SetAttribute.Editor {
    public final Component parentComponent;
    public final String title;

    public Chooser(Component parentComponent, String title) {
        this.parentComponent = parentComponent;
        this.title = title;
    }

    public String editAttributeValue(String attributeValue) {1
        Color color = fromHexString(attributeValue.trim());
        if (color == null) {
            color = Color.black;
        }

        color = JColorChooser.showDialog(parentComponent, title, color);
        if (color == null) {
            return null;
        }

        return toHexString(color);
    }
}

1

The SetAttribute.Editor specifies a single method: editAttributeValue. This method is passed the current value of the attribute. It must display the modal dialog box. If the user clicks Cancel, this method returns null. If the user clicks OK, this method returns a new value of the attribute being edited.