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"

(→‎Read-Only Widgets)
(→‎Security Filters)
Line 219: Line 219:
 
== Catalogue Modifiers ==
 
== Catalogue Modifiers ==
  
−
== Security Filters ==
+
== Password fields & filters ==
 +
 
 +
Password fields provide
 +
 
 +
=== Password Fields ===
 +
{| border="1" cellspacing="0" cellpadding="4"
 +
|- valign="top"
 +
! Annotation
 +
| <xefgui:widget>password</xefgui:widget>
 +
|- valign="top"
 +
! Description
 +
| Hides the values entered by the user by providing two blind password fields.
 +
|- valign="top"
 +
! Applies to
 +
| attributes of type <xs:string>
 +
|- valign="top"
 +
! Before
 +
| [[Image:XEFPasswordBefore.jpg]]
 +
|- valign="top"
 +
! After
 +
| [[Image:XEFPasswordAfter.jpg]]
 +
|- valign="top"
 +
! Example
 +
|
 +
|}
 +
 
 +
 
 +
=== Password Filters ===
 +
{| border="1" cellspacing="0" cellpadding="4"
 +
|- valign="top"
 +
! Annotation
 +
| <xef:filter> - (filter ID)
 +
|- valign="top"
 +
! 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 <code>TextFilter</code> interface:
 +
<pre> package org.eclipse.stp.ui.xef.editor;
 +
 
 +
public interface TextFilter {
 +
    public String filter(String data);
 +
}</pre>
 +
New password filters can be provided in eclipse plugins and need to be registered through the <code>filter</code> element in the <code>org.eclipse.stp.xef.xefExtension</code> extension point.
 +
 
 +
A number of sample filters are provided with the XEF editor, e.g. <code>org.eclipse.stp.ui.xef.editor.SimpleHashFilter</code>. This filter is registered as follows in the <code>plugin.xml</code>:
 +
<pre><extension point="org.eclipse.stp.xef.xefExtension">
 +
  <filter class="org.eclipse.stp.ui.xef.editor.SimpleHashFilter"
 +
          filterId="SimpleHashFilter"/>
 +
</extension></pre>
 +
The <code>filterId</code> gives the filter a name by which it can be referenced in the XML schema annotation.
 +
 
 +
There is also a <code>PlainTextFilter</code> 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.
 +
|- valign="top"
 +
! Applies to
 +
| attributes of type <xs:string>
 +
|- valign="top"
 +
! Before
 +
| The password text uses the default filter to protect passwords, for a password "abcd" entered, the XML would contain the following:
 +
<pre><example:audit xmlns:example="http://www.example.com/xsd/2006/02/test_audit" lock_password="2987074" /></pre>
 +
|- valign="top"
 +
! 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:
 +
<pre><example:audit xmlns:example="http://www.example.com/xsd/2006/02/test_audit" lock_password="dcba" /></pre>
 +
|- valign="top"
 +
! Example
 +
| <pre><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</pre>
 +
|}

Revision as of 06:00, 13 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>


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>


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

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


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=68296"

Back to the top