1. attributeEditor

1. attributeEditor
	Chapter 6. Configuration elements

<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|URL)
  value = string
/>

<list
  allowAnyValue = boolean : false
  allowWhitespace = boolean : dynamic
  allowMultipleValues = boolean : false
  valueSeparator = string containing a single character : " "
  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:

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>

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:

The Value field which supports auto-completion will display the items of the list.
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 attributeEditors 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</item>
    <item>external</item>
  </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>

DocBook example:

<attributeEditor attribute="userlevel" elementMatches="*">
  <list allowMultipleValues="true" valueSeparator=";">
    <item>beginner</item>
    <item>intermediate</item>
    <item>advanced</item>
    <item>expert</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>


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>

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 valueSeparator.
valueSeparator: Character used to separate tokens. Default to the whitespace character (U+0020), which means: any whitespace character. Ignored unless allowMultipleValues is true.

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.