Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "STP/Policy Component/XEF Reference"

(→‎Display Name)
(→‎Multi-line text)
Line 160: Line 160:
 
|- valign="top"
 
|- valign="top"
 
! Description
 
! Description
−
| Provides a human readable name for the attribute or element.
+
| 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.
 
|- valign="top"
 
|- valign="top"
 
! Applies to  
 
! Applies to  
−
| <xs:element> and <xs:attribute>
+
| <xs:attribute> of type <xs:string>
 
|- valign="top"
 
|- valign="top"
 
! Before
 
! Before
−
|
+
| [[Image:XEFMultilineBefore.jpg]]  
−
attributes: [[Image:DisplayNameBefore.jpg]]
+
−
 
+
−
 
+
−
 
+
−
elements: [[Image:DisplayNameElementBefore.jpg]]
+
 
|- valign="top"
 
|- valign="top"
 
! After
 
! After
−
|
+
| [[Image:XEFMultilineAfter.jpg]]
−
attributes: [[Image:DisplayNameAfter.jpg]]
+
−
 
+
−
 
+
−
 
+
−
elements: [[Image:DisplayNameElementAfter.jpg]]
+
 
|- valign="top"
 
|- valign="top"
 
! Example
 
! Example
 
|  
 
|  
−
<pre><xs:attribute name="every_client" type="xs:boolean">
+
<pre><xs:attribute name="prefix" type="xs:string">
 
   <xs:annotation>
 
   <xs:annotation>
 
     <xs:appinfo>
 
     <xs:appinfo>
−
       <xef:displayName>Every Client</xef:displayName>
+
       <xefgui:widget>multiline</xefgui:widget>
 
     </xs:appinfo>
 
     </xs:appinfo>
 
   </xs:annotation>
 
   </xs:annotation>

Revision as of 05:59, 14 December 2007

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 addition information in the schema, or by providing annotations. 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]

Below you can find a list 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: XEFCategoryBefore.jpg


elements: XEFCategoryElementBefore.jpg

After

attributes: XEFCategoryAfter1.jpg and XEFCategoryAfter2.jpg


elements: XEFCategoryElementAfter.jpg

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


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

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>

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

Catalogue Modifiers

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 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
Retrieved from "https://wiki.eclipse.org/index.php?title=STP/Policy_Component/XEF_Reference&oldid=68555"

Back to the top