XEF Reference
The way the XEF editor renders widgets is based on the XML Schema definition of
the elements and attributes. It can be influenced by putting additional
information in the schema and by providing special annotations in the schema. The annotations are
divided over two namespaces, xef (http://schemas.eclipse.org/stp/xsd/2006/05/xef) and xefgui (http://schemas.eclipse.org/stp/xsd/2006/05/xef/gui). The xef namespace contains
information that is not purely GUI-related (e.g. it could also be used for
non-gui purposes such as generating extra documentation around an element). The
xefgui namespace contains purely widget-related information.
The xef and xefgui namespaces are documented in their own XML-Schema files that
can be found in the following locations:
[xef]
[xefgui]
This page provides a reference of the various ways in which the XEF editor can be influenced.
Basics
Category
Annotation
|
<xef:category> - String
|
Description
|
Provides categorization for the element or attribute. For elements the category is used in the Schema Selection Dialog, for attributes the category is used to put the attribute in a collapsible section in the editor.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
attributes:
elements:
|
After
|
attributes: and
elements:
|
Example
|
<xs:element name="audit">
<xs:annotation>
<xs:appinfo>
<xef:category>Logging</xef:category>
</xs:appinfo>
</xs:annotation>
</xs:element>
|
Boolean values
Annotation
|
<xefgui:widget>check</xefgui:widget> or <xefgui:widget>radio</xefgui:widget>
|
Description
|
Boolean values can be rendered as a set of radio buttons or as a single check box. Radio buttons are currently the default.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="every_call" type="xs:boolean">
<xs:annotation>
<xs:appinfo>
<xefgui:widget>check</xefgui:widget>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Defaults
Annotation
|
default="..." in schema
|
Description
|
Displays the default value of an attribute greyed out in the control. When the value is displayed like this the actual default value is not inserted in the edited focument. The user can still edit the control value to insert another value. Toggeling between the default value and the user-entered value can be done with the (D) button beside the control.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="sample_interval" type="xs:int" default="5000">
|
Display Name
Annotation
|
<xef:displayName> - String
|
Description
|
Provides a human readable name for the attribute or element.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
attributes:
elements:
|
After
|
attributes:
elements:
|
Example
|
<xs:attribute name="every_client" type="xs:boolean">
<xs:annotation>
<xs:appinfo>
<xef:displayName>Every Client</xef:displayName>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Documentation and Help
Annotation
|
<xs:documentation>
|
Description
|
Documentation as provided in the standard XML Schema <xs:documentation> annotation is shown in the XEF Help view and is context sentitive. The help view uses an embedded browser so XHTML tags can be embedded in the documentation.
Also note that the xml:lang="..." attribute is adhered to, so documentation can be provided in multiple languages, only the language appropriate for the current locale is displayed.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Effect
|
|
Example
|
<xs:element name="audit">
<xs:annotation>
<xs:documentation>The <b>audit policy</b> provides auditing information in the service's audit logs.
<ul>
<li>feature 1</li>
<li>feature 2</li>
</ul>
</xs:documentation>
<xs:documentation xml:lang="fr">Ici en français.</xs:documentation>
</xs:annotation>
</xs:element>
|
Drop-down Combo
Annotation
|
<xefgui:widget>multiline</xefgui:widget>
|
Description
|
By specifying that an attribute or element is a simple type that restricts the string type, a drop-down combo will be rendered to represent all the values of the enumeration.
|
Applies to
|
<xs:attribute> of type <xs:string>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="level" default="Info">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Fatal"/>
<xs:enumeration value="Error"/>
<xs:enumeration value="Warning"/>
<xs:enumeration value="Info"/>
<xs:enumeration value="Debug"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
|
Multi-line text
Annotation
|
<xefgui:widget>multiline</xefgui:widget>
|
Description
|
Renders a multiline text entry field. This annotation is needed for attributes only. Elements of type xs:string already get a multiline field by default.
|
Applies to
|
<xs:attribute> of type <xs:string>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="prefix" type="xs:string">
<xs:annotation>
<xs:appinfo>
<xefgui:widget>multiline</xefgui:widget>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Pattern validation
Annotation
|
<xef:pattern>
|
Description
|
Ensures that the value entered matches the regular expression pattern.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="hexcode" type="xs:string" >
<xs:annotation>
<xs:appinfo>
<xef:pattern>[0-9A-Z]*</xef:pattern>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Read-Only Widgets
Getting a field displayed using read-only widgets is possible in two ways:
- using the
fixed="..."
attribute in the XML Schema definition. This doesn't allow the value to be changed at all.
- There is an alternative for when it's desirable that the editor doesn't change it. The use of
<xefgui:widget>read_only</xefgui:widget>
simply draws a readonly widget. In this case the value can still be changed in the underlying XML.
In both cases the way the read-only field is presented to the user is the same.
Fixing the value in the Schema
Annotation
|
<xs:element ... fixed="my fixed value">
|
Description
|
Fixes the value of an attribute or element in the schema.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="output" type="xs:string" fixed="System Console" />
|
Marking the widget as Read-Only
Annotation
|
<xefgui:widget>read_only</xefgui:widget>
|
Description
|
Creates read-only widgets in the editor.
|
Applies to
|
<xs:element>, <xs:attribute> and <xs:any>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="output" type="xs:string" >
<xs:annotation>
<xs:appinfo>
<xefgui:widget>read_only</xefgui:widget>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Required text and examples
Required attributes can be marked as such in the XML Schema. The XEF editor adheres to this. Requires attributes can't have a default value. To help the user with filling in these attributes, the <xef:example> annotation can be used.
Required text field
Examples for required text fields
Annotation
|
<xef:example> - (String)
|
Description
|
Required attributes can't have a default value in the XML schema. However, sometimes it can be friendly towards users to provide them with an example value. This might help the user to understand how this field needs to be filled in. There is a difference between <xef:example> and default values for attributes. <xef:example> only makes sense in the context of required attributes. Even if the user doesn't change the value as specified with <xef:example> the value will always be stored in the document. With defaults, the value will not be stored if the default is used.
|
Applies to
|
<xs:attribute> with use="required"
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="url" type="xs:string" use="required">
<xs:annotation>
<xs:appinfo>
<xef:example>http://{machine}:8080/ctx</xef:example>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Spinners
Annotation
|
type="..." with types that represent integers >= 0
|
Description
|
Elements and attributes that have an integer type >= 0 will be rendered as spinner controls. Since spinners can't show negative values types that can hold negative values will not be rendered as a spinner.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="sample_interval" type="xs:positiveInteger" default="5000"/>
|
Tool Tips
Annotation
|
<xef:docShort> - String
|
Description
|
Provides tooltips on the controls that display the elements and attributes.
|
Applies to
|
<xs:element> and <xs:attribute>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="sample_interval" type="xs:positiveInteger">
<xs:annotation>
<xs:appinfo>
<xef:docShort>Defines how often the log is sampled for auditing</xef:docShort>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Units
Annotation
|
<xef:units> - String
|
Description
|
Places an extra label to describe the units of measurement for the attribute in the editor.
|
Applies to
|
<xs:attribute>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="sample_interval" type="xs:int" default="5000">
<xs:annotation>
<xs:appinfo>
<xef:units>ms</xef:units>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Password fields & filters
Password fields provide a way to hide what the user types in as a password. Password filters provide a puggable way to process these passwords before they are stored in the XML.
Password Fields
Annotation
|
<xefgui:widget>password</xefgui:widget>
|
Description
|
Hides the values entered by the user by providing two blind password fields.
|
Applies to
|
attributes of type <xs:string>
|
Before
|
|
After
|
|
Example
|
<xs:attribute name="lock_password" type="xs:string">
<xs:annotation>
<xs:appinfo>
<xef:displayName>Lock Password</xef:displayName>
<xefgui:widget>password</xefgui:widget>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
|
Password Filters
Annotation
|
<xef:filter> - (filter ID)
|
Description
|
Password filtering allows the password entered using a password widget to be processed before it is stored in the XML file. This prevents users from seeing the actual password entered by looking at the XML source of the document being edited.
Password filters implement the TextFilter interface:
package org.eclipse.stp.ui.xef.editor;
public interface TextFilter {
public String filter(String data);
}
New password filters can be provided in eclipse plugins and need to be registered through the filter element in the org.eclipse.stp.xef.xefExtension extension point.
A number of sample filters are provided with the XEF editor, e.g. org.eclipse.stp.ui.xef.editor.SimpleHashFilter . This filter is registered as follows in the plugin.xml :
<extension point="org.eclipse.stp.xef.xefExtension">
<filter class="org.eclipse.stp.ui.xef.editor.SimpleHashFilter"
filterId="SimpleHashFilter"/>
</extension>
The filterId gives the filter a name by which it can be referenced in the XML schema annotation.
There is also a PlainTextFilter pre-registered that does no processing at all and leaves the password in clear text in the XML. This is not the default filter and usage of this filter is discouraged.
|
Applies to
|
attributes of type <xs:string>
|
Before
|
The password text uses the default filter to protect passwords, for a password "abcd" entered, the XML would contain the following:
<example:audit xmlns:example="http://www.example.com/xsd/2006/02/test_audit"
lock_password="2987074" />
|
After
|
The password uses our ReverseTextFilter, which is not very secure but clearly demonstrates the filtering functionality. This filter simply reverses the string, so the XML will be:
<example:audit xmlns:example="http://www.example.com/xsd/2006/02/test_audit"
lock_password="dcba" />
|
Example
|
<xs:attribute name="lock_password" type="xs:string">
<xs:annotation>
<xs:appinfo>
<xef:displayName>Lock Password</xef:displayName>
<xef:filter>ReverseTextFilter</xef:filter>
<xefgui:widget>password</xefgui:widget>
</xs:appinfo>
</xs:annotation>
</xs:attribute
|
Context-sensitive values
... need to write this section ...
Subelements in <xs:sequence> and <xs:choice> groups
XML Schema defined elements can have sub-elements if the element is of type xs:complexType.
Currently xs:choice and xs:sequence definitions of complex types are supported.
An element having potential sub-elements is marked with a small 'plus' sign as a hint to the user that sub-elements are available.
<xs:choice>
Description
|
Choice elements are shown in the pop-up menu of the element on the left-hand side of the editor. Once any one of the choice elements is selected, none of the other choice elements will be offered (unless the previously selected element is removed first).
|
Applies to
|
<xs:element> of type xs:complexType
|
Before choosing a sub-element
|
|
After choosing a sub-element
|
|
Example
|
<xs:element name="logging">
<xs:complexType>
<xs:choice>
<xs:element name="ConsoleLogger"/>
<xs:element name="FileLogger"/>
<xs:element name="QueueLogger"/>
</xs:choice>
</xs:complexType>
</xs:element>
|
<xs:sequence>
Description
|
Like choice elements, sequence elements are also shown in the pop-up menu of the element on the left-hand side of the editor. The editor adheres to the minOccurs and maxOccurs attributes on the sub-elements. So if the minOccurs >= 1, new subelement(s) will be created automatically when the parent element is created. If the maxOccurs != "unbounded" the sub element will not be offered as an option any more if the maximum number of occurrences has been reached. Note that the default values of minOccurs and maxOccurs as per the XML Schema specification is both "1".
|
Applies to
|
<xs:element> of type xs:complexType
|
Before choosing a sub-element
|
|
After choosing a sub-element
|
|
Example
|
<xs:element name="logging">
<xs:complexType>
<xs:sequence>
<xs:element name="header" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="prefix" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="footer" type="xs:string" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
|
minOccurs / maxOccurs
Catalogue Modifiers
Elements requiring other elements
Elements inhibiting other elements
Unique Elements
Registering specific field editors
Supported XML Schema data types
- xsd:boolean
- xsd:byte
- xsd:decimal (currently unvalidated)
- xsd:double (currently unvalidated)
- xsd:float (currently unvalidated)
- xsd:int (currently unvalidated)
- xsd:integer (currently unvalidated)
- xsd:long (currently unvalidated)
- xsd:NCName
- xsd:negativeInteger (currently unvalidated)
- xsd:nonNegativeInteger
- xsd:nonPositiveInteger (currently unvalidated)
- xsd:positiveInteger
- xsd:QName - Renders a QName editor
- xsd:short (currently unvalidated)
- xsd:string
- xsd:unsignedByte
- xsd:unsignedInt
- xsd:unsignedLong (currently unvalidated)
- xsd:unsignedShort
other schema types work too but will render as a text field.