Latest revision as of 11:27, 25 February 2008

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.

Note that a getting started guide on the XEF editor can be found here: http://wiki.eclipse.org/STP/Policy_editor_documentation .

Basics

Category

Annotation	<xef:category> - String
Description	Provides categorization for attributes. The category is used to put the attribute in a collapsible section in the editor.
Applies to	<xs:attribute>
Before
After	and
Example	<xs:attribute name="sample_interval" type="xs:positiveInteger"> <xs:annotation> <xs:appinfo> <xef:category>Advanced</xef:category> </xs:appinfo> </xs:annotation> </xs:attribute>

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 document. The user can still edit the control value to insert another value. Toggling 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

<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 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	<xs:restriction> and <xs:enumeration>
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 multi line text entry field. This annotation is required for attributes only. Elements of type xs:string already get a multi line 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:

1. using the fixed="..." attribute in the XML Schema definition. This doesn't allow the value to be changed at all.
2. 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

Annotation	use="required"
Description	The user will have to provide a value for required attributes. The editor enforces this. Required attributes can't have a default, so they are be rendered without a default button.
Applies to	<xs:attribute>
Before
After	when trying to save an unspecified attribute, an error message will be shown, and save is not allowed:
Example	<xs:attribute name="every_call" type="xs:string" use="required"/>

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. Note that XML Schema doesn't allow default="..." to be specified when use="required" is present.
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	Provide a short, single line of documentation (in addition to the <xs:documentation> annotation) that would typically be used in tool-tips on the controls.
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

package org.eclipse.stp.ui.xef.editor;

public interface TextFilter {
    public String filter(String data);
}

<extension point="org.eclipse.stp.xef.xefExtension">
  <filter class="org.eclipse.stp.ui.xef.editor.SimpleHashFilter"
          filterId="SimpleHashFilter"/>
</extension>

<example:audit xmlns:example="http://www.example.com/xsd/2006/02/test_audit"
               lock_password="2987074" />

<example:audit xmlns:example="http://www.example.com/xsd/2006/02/test_audit"
               lock_password="dcba" />

<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

It is possible to pre-populate combo boxes with values that do not come directly from schema, but from the context of the application. To enable this functionality an IContextProvider callback object needs to be provided with the XMLProviderEditorInput. The org.eclipse.stp.ui.xef.schema.IContextProvider interface has the following api:

package org.eclipse.stp.ui.xef.schema;
public interface IContextProvider {
    public Object getData(String ctxId);
    public String[] getValues(String ctxId, String ctxFilter);
}

For context-sensitive values the getValues() callback will be made on this object which can then provide information from the underlying application.

As an example take the following policy schema element definition:

<xs:element name = "target">
  <xs:complexType>
    <xs:attribute name="service" type="xs:string">
      <xs:annotation>
        <xs:appinfo>
          <xefgui:context>
            <xefgui:values>target_service</xefgui:values>
          </xefgui:context>
        </xs:appinfo>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="port" type="xs:string">
      <xs:annotation>
        <xs:appinfo>   
          <xefgui:context>
            <xefgui:values>endpoint</xefgui:values>
            <xefgui:dependency>@service</xefgui:dependency>
          </xefgui:context>
          <xefgui:widget>read_write</xefgui:widget>          
        </xs:appinfo>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
</xs:element>

The service attribute has as context values the identifier target_service. This identifier is passed into the ctxId argument of the getValues() method of the IContextProvider callback to obtain the values that are possible for this attribute. The returned values will be displayed as a drop-down combo box in the editor. The port attribute similarly has a context values identifier of endpoint. There is another attibute here: the dependency annotation. This defines when the values in the combo box will need to be refreshed. An XPath to another attribute can be specified. When the value of the specified attribute changes, the values in the combo box will be reloaded. When this happens, the attribute that triggered the reload is passed in as the ctxFilter argument to the getValues() method. So the possible values in the port attribute change.

One more thing to note: the <xefgui:widget>read_write</xefgui:widget> annotation. This causes the combo box generated to be not strict, so the user can type in values other than the ones suggested in this combo box too for the port attribute, where the service attribute is more strict and doesn't allow any other values to be specified.

My Context Provider implementation is as follows and will need to be passed as an argument to the XMLProviderEditorInput when opening the editor.

package org.eclipse.stp.ui.xef.editor;
import org.eclipse.stp.ui.xef.schema.IContextProvider;

public class MyContextProvider implements IContextProvider {
    public Object getData(String ctxId) {
        return null;
    }

    public String[] getValues(String ctxId, String ctxFilter) {
        if ("target_service".equals(ctxId)) {
            return new String [] {"Service 1", "Service 2"};
        } else if ("Service 1".equals(ctxFilter) && "endpoint".equals(ctxId)) {
            return new String [] {"s1ep1", "s1ep2"};
        } else if ("Service 2".equals(ctxFilter) && "endpoint".equals(ctxId)) {
            return new String [] {"s2ep"};
        }
        return new String [] {};
    }
}

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

Sequence of <xs:any>

Description	To embed any kind of XML at a certain point inside an element, use a sequence of <xs:any> elements. The XEF editor will render this in a special way end provides an editing dialog that has XML colour coding. Note that the <xs:any> element can also hold most xef annotations, such as <xef:displayName>, <xef:docShort> etc.
Applies to	<xs:element> of type xs:complexType
In the editor
The editing dialog
Example	<xs:element name="any_policy"> <xs:complexType> <xs:sequence> <xs:any /> </xs:sequence> </xs:complexType> </xs:element>

Catalogue Modifiers

Category

Annotation	<xef:category> - String
Description	The category is used in the Schema Selection Dialog to group policies in categories.
Applies to	<xs:element>
Before
After
Example	<xs:element name="audit"> <xs:annotation> <xs:appinfo> <xef:category>Logging</xef:category> </xs:appinfo> </xs:annotation> </xs:element>

Elements inhibiting other elements

Sometimes only one element of a certain type should be allowed to be added. E.g. the XEF editor used as a policy editor should only allow one transport policy at a time. This behaviour can be achieved by specifying qualifiers. In the following example there are two policies, one for CORBA and another one for HTTP. The CORBA policy implies both a binding and a transport, where the HTTP binding only relates to the transport:

<xs:element name="corba">
  <xs:annotation>
    <xs:appinfo>
      <xef:qualifier multiple="false">binding</xef:qualifier>
      <xef:qualifier multiple="false">transport</xef:qualifier>
    </xs:appinfo>
  </xs:annotation>
</xs:element>
<xs:element name="http">
  <xs:annotation>
    <xs:appinfo>
      <xef:qualifier multiple="false">transport</xef:qualifier>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

When elements are given a qualifier with multiple="false" multiple elements with that qualifier won't be allowed. In the example, when a document already has the HTTP policy, the CORBA policy can't be added because the transport qualifier is only allowed once:

Elements requiring other elements

Certain elements are only valid in the context of other elements. For example a HTTPS element may only make sense in the context of a HTTP element. This can be specified with the requires annotation which takes the QName of the element that is required for the current element to be enabled:

<xs:element name="https">
  <xs:annotation>
    <xs:appinfo>
      <xef:requires>
      	<xef:element_qname>{http://www.example.com/xsd/2007/02/test_http}http</xef:element_qname>
      </xef:requires>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

Multiple requirements can be specified within a single requires section. If there are alternatives, multple requires sections can be specified. The following element requires either HTTP and SOAP or alternatively requires CORBA.

<xs:element name="some_element">
  <xs:annotation>
    <xs:appinfo>
      <xef:requires>
      	<xef:element_qname>{http://www.example.com/xsd/2007/02/test_http}http</xef:element_qname>
      	<xef:element_qname>{http://www.example.com/xsd/2007/02/test_soap}soap</xef:element_qname>
      </xef:requires>
      <xef:requires>
      	<xef:element_qname>{http://www.example.com/xsd/2007/05/test_corba}corba</xef:element_qname>
      </xef:requires>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

Unique Elements

By default, elements are considered to be unique, meaning that only a single instance of a given element can be added to a document. (Note: this default can be reversed by providing the POLICIES_UNIQUE Setting when opening the editor).

If a given element needs to deviate from the default, this can be specified with the unique annotation. Consider a 'config' element that would be allowed more than once in a document while other elements, such as HTTP would only be allowed once. This can be achieved using the following schema:

<xs:element name="config">
  <xs:annotation>
    <xs:appinfo>
      <xef:unique>false</xef:unique>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

In the following example you can see that the editor won't allow multiple HTTP policies specified, but it does allow multiple 'config' policies specified:

The <xef:unique> annotation can take false or true as values and when not specified, the element will get the default behaviour for multiplicity.

Registering specific field editors

Sometimes you may have values in your XML document that require a specific field editor in order to be conveniently edited.

For example, you may have an attribute that represents a contact person for a certain entity and you'd like the users to properly fill in the first and last name of this person.

To achieve this, a custom field editor can be registered via an Extension Point. When an attribute is marked with the fieldEditor annotation, it will get a '...' button beside it and editing is done in a dialog specifically created for this type of field.

Creating a Field Editor

First, create a dialog class that extends org.eclipse.stp.ui.xef.editor.AbstractFieldEditor. This class will contain the actual dialog code:

package org.eclipse.stp.xef.test;

import java.util.StringTokenizer;

import org.eclipse.stp.ui.xef.editor.AbstractFieldEditor;
import org.eclipse.swt.SWT;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.*;

public class MyFieldEditor extends AbstractFieldEditor {
    private Text firstName;
    private Text lastName;
    private String result;

    public MyFieldEditor() {
        super(null);
    }

    protected void configureShell(Shell newShell) {
        super.configureShell(newShell);
        newShell.setText("Enter details");
    }

    protected Control createDialogArea(Composite parent) {
        Composite area = (Composite) super.createDialogArea(parent);
        final GridLayout gridLayout = new GridLayout();
        gridLayout.numColumns = 2;
        gridLayout.makeColumnsEqualWidth = false;
        area.setLayout(gridLayout);
        
        new Label(area, SWT.NONE).setText("First Name: ");
        firstName = new Text(area, SWT.BORDER);
        new Label(area, SWT.NONE).setText("Last Name: ");
        lastName = new Text(area, SWT.BORDER);
        return area;
    }
    
    protected void okPressed() {
        result = firstName.getText() + " " + lastName.getText();
        super.okPressed();
    }

    public String getFieldText() {
        return result;
    }

    public void setFieldText(String text) {
        result = text;
        try {
            StringTokenizer tok = new StringTokenizer(text);
            firstName.setText(tok.nextToken());
            lastName.setText(tok.nextToken());
        } catch (Throwable e) {
        }        
    }

    public void setFieldData(Object data) {}
}

The getFieldText() and setFieldText() are the interface with the outside world. setFieldText() will be called by the framework to initialize the dialog with the current value (if any). The getFieldText() method will be called when the framework wants to obtain the value of the field editor. Note that this method is called when the dialog is already closed, so you will have to store the result in a member variable, possibly in the okPressed() method.

Then register the field editor with a XEF extension point, in the example below it is registered under the nameFieldEditor ID.

<extension point="org.eclipse.stp.xef.xefExtension">
  <fieldEditor class="org.eclipse.stp.xef.test.MyFieldEditor"
               fieldEditorId="nameFieldEditor">
  </fieldEditor>
</extension>

Using the Custom Field Editor

Finally, mark the attribute that requires the special Field Editor with the <xef:fieldEditor> annotation. The field editor is referenced by ID. In the screenshot above the following attribute definition was used:

<xs:attribute name="contact_person" type="xs:string">
  <xs:annotation>
    <xs:appinfo>   
      <xef:fieldEditor>nameFieldEditor</xef:fieldEditor>
    </xs:appinfo>
  </xs:annotation>
</xs:attribute>   

Supported XML Schema data types

• xsd:boolean
• xsd:byte
• xsd:int
• xsd:integer
• xsd:long
• xsd:NCName
• xsd:negativeInteger
• xsd:nonNegativeInteger
• xsd:nonPositiveInteger
• xsd:positiveInteger
• xsd:QName - pops up a QName Field Editor
• xsd:short
• xsd:string
• xsd:unsignedByte
• xsd:unsignedInt
• xsd:unsignedShort

other schema types work too but will render as a text field.