1. attributeEditor
Prev | Chapter 7. Configuration elements | Next

## 1. attributeEditor

    <attributeEditor
      attribute = Name
      elementMatches = XPath pattern
    >
      Content: [ class [ property ]* ]? |
               [ list ]?
    </attributeEditor>

    <class>
      Content: Java class name
    </class>

    <property
      name = NMTOKEN matching [_a-zA-Z][_a-zA-Z0-9]*
      type = (boolean|byte|char|short|int|long|float|double|
              String)
      value = string
    />

    <list
      allowAnyValue = boolean : false
      allowWhitespace = boolean : dynamic
      allowMultipleValues = boolean : false
      selectItems = XPath expression
      itemValue = XPath expression
      itemDescription = XPath expression
    >
      Content: [ item ]*
    </list>

    <item
      description = Non empty token
    >
      Content: Non empty string
    </item>

The `attributeEditor` configuration element allows to extend 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:

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

These extensions are used by the Attributes tool 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.

Note that when an extension returns a list, a specialized dialog box may be automatically wrapped around this list. That is, when an extension returns a list, not only the Value field will provide auto-completion for the attributes values, but also the Edit popup menu item will display a specialized dialog box.

The attributes of the `attributeEditor` configuration element are used to detect attributes for which a custom editor is to be created:

`attribute`

  The XML qualified name of the attribute.

`elementMatches`

  An XPath pattern matching the elements possibly having the attribute whose name is specified by above attribute `attribute`.

Note that an `attributeEditor` is uniquely identified by its `attribute` and `elementMatches` attributes and also by the name of the configuration containing it. For example, the following `attributeEditor`s do not conflict provided that they are defined in different configurations:

    <attributeEditor attribute="ref" elementMatches="*">
      <list selectItems="//part/@number" />
    </attributeEditor>

    <attributeEditor attribute="ref" elementMatches="*">
      <list>
        <item>internal</items>
        <item>external</items>
      </list>
    </attributeEditor>

The child elements the `attributeEditor` configuration element are used to specify how the custom editor is to be implemented by the Attributes tool:

`class`

  This element contains the fully qualified name of a class which implements one or both of the following interfaces: `com.xmlmind.xmledit.cmd.attribute.SetAttribute.ChoicesFactory`, `com.xmlmind.xmledit.cmd.attribute.SetAttribute.EditorFactory`.

  The `property` child elements of the class element allow to parameterize the newly created instance of this class. See bean properties.

  DocBook example:

      <attributeEditor attribute="linkend" elementMatches="xref|link">
        <class>com.xmlmind.xmleditapp.linktype.RefChoicesFactory</class>
        <property name="listIfMemberOfDocSet" type="boolean" value="true" />
      </attributeEditor>

`list`

  This element specifies all possible values for a given attribute. The items of this list may be statically described by the means of the `item` child element or dynamically computed by the means of the `selectItems`, `itemValue` and `itemDescription` XPath expressions.

  ### Static lists

  A static list comprises only the items specified by its `item` child elements. The string contained in the `item` element specifies the value of the item. The optional `description` attribute provides a description of this value.

  Items are automatically sorted by their values. Duplicate items are automatically removed.

  DITA example:

      <attributeEditor attribute="audience" elementMatches="*">
        <list allowMultipleValues="true">
          <item description="A user of the product">user</item>
          <item description="A product purchaser">purchaser</item>
          <item description="A product administrator">administrator</item>
          <item description="A programmer">programmer</item>
          <item description="An executive">executive</item>
          <item description="Someone who provides services
                             related to the product">services</item>
        </list>
      </attributeEditor>

  ### Dynamic lists

  Unless a list has `item` child elements, specifying at least attribute `selectItems` is mandatory.

  `selectItems`

    Returns a node set enumerating all list items. This XPath expression is evaluated in the context of the element having the attribute being edited by the Attributes tool.

  `itemValue`

    This XPath expression is evaluated in the context of each node returned by `selectItems`. It returns a string which is the value of the item. Items having an empty value are discarded.

    When this attribute is missing, the value of an item is the string value of the node selected by `selectItems`.

  `itemDescription`

    This XPath expression is evaluated in the context of each node returned by `selectItems`. It returns a string which is the description of the item. Empty descriptions are ignored.

    When this attribute is missing, an item has no description.

  Items are automatically sorted by their values. Duplicate items are automatically removed.

  XHTML example:

      <attributeEditor attribute="for" elementMatches="html:label">
        <list selectItems="//html:input|//html:select" itemValue="@id"
              itemDescription="concat(local-name(.), ' ', @type)"
              allowWhitespace="false" />
      </attributeEditor>

  ### Tip

  A convenient way to describe an element is to use XPath extension function `sa:getElementDescription(`nodeset_returning_an_element`)`, where prefix "`sa`" is bound to namespace "`java:com.xmlmind.xmledit.cmd.attribute.SetAttribute`".

  For example, the above XHTML example could be rewritten as:

      <attributeEditor attribute="for" elementMatches="html:label">
        <list selectItems="//html:input|//html:select" itemValue="@id"
              itemDescription="sa:getElementDescription(.)"
              xmlns:sa="java:com.xmlmind.xmledit.cmd.attribute.SetAttribute"
              allowWhitespace="false" />
      </attributeEditor>

  ### Other `list` attributes

  allowAnyValue

    Allow the user to specify values other than the ones coming from the list.

  allowWhitespace

    List items may have values containing whitespace. When the list is static, the default value of this attribute is determined by examining all the items of the list. When the list is dynamic, the default value of this attribute is `true`.

  allowMultipleValues

    The value of the attribute may contain one or more tokens (coming from the values of the list items) separated by whitespace.

  Remember that a custom attribute editor specified using `attributeEditor` is just here to help the user specify an attribute value. It's not really designed to validate what the user specifies. It's up to the underlying DTD or schema to perform this validation task.

An `attributeEditor` element without any child element may be used to remove from a configuration a previously defined `attributeEditor` having the same `attribute` and `elementMatches` attributes.

Prev | Up | Next
Chapter 7. Configuration elements | Home | 2. binding