Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

STP/Policy Component/XEF Reference

< STP‎ | Policy Component
Revision as of 11:02, 18 January 2008 by Davidb.iona.com (Talk | contribs) (Context-sensitive values)

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 XEFCategoryBefore.jpg
After XEFCategoryAfter1.jpg and XEFCategoryAfter2.jpg
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 XEFBooleanBefore.jpg
After XEFBooleanAfter.jpg
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 XEFDefaultBefore.jpg
After XEFDefaultAfter.jpg
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: DisplayNameBefore.jpg


elements: DisplayNameElementBefore.jpg

After

attributes: DisplayNameAfter.jpg


elements: DisplayNameElementAfter.jpg

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 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 XEFHelpAfter.jpg
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 XEFComboBefore.jpg
After XEFComboAfter.jpg
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 XEFMultilineBefore.jpg
After XEFMultilineAfter.jpg
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 XEFPatternBefore.jpg
After XEFPatternAfter.jpg
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 XEFFixedBefore.jpg
After XEFFixedAfter.jpg
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 XEFFixedBefore.jpg
After XEFFixedAfter.jpg
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 XEFRequiredBefore.jpg
After XEFRequiredAfter1.jpg

when trying to save an unspecified attribute, an error message will be shown, and save is not allowed: XEFRequiredAfter2.jpg

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 XEFReqExampleBefore.jpg
After XEFReqExampleAfter.jpg
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 XEFSpinnerBefore.jpg
After XEFSpinnerAfter.jpg
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 XEFToolTipBefore.jpg
After XEFToolTipAfter.jpg
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 XEFUnitsBefore.jpg
After XEFUnitsAfter.jpg
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 XEFPasswordBefore.jpg
After XEFPasswordAfter.jpg
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 org.eclipse.stp.ui.xef.editor.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

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

}

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 XEFChoiceBefore.jpg
After choosing a sub-element XEFChoiceAfter.jpg
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 XEFSequenceBefore.jpg
After choosing sub-elements XEFSequenceAfter.jpg
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 XEFAnyEditor.jpg
The editing dialog XEFAnyDialog.jpg
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 XEFCategoryElementBefore.jpg
After XEFCategoryElementAfter.jpg
Example
<xs:element name="audit">
  <xs:annotation>
    <xs:appinfo>
      <xef:category>Logging</xef:category>
    </xs:appinfo>
  </xs:annotation>
</xs:element>


Elements requiring other elements

Elements inhibiting other elements

Unique Elements

Registering specific field editors

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 - Renders a QName editor
  • xsd:short
  • xsd:string
  • xsd:unsignedByte
  • xsd:unsignedInt
  • xsd:unsignedShort

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

Back to the top