# What is XEF?

XEF is a mechanism for editing XML content using a widget-based Editor (with various kinds of controls, tooltips, dynamic help and other features). The editor provided by XEF is dynamically synthesized based on the XML Schema that defines the XML. Logically XEF works like this:

Input to the editor is the current XML (of the piece of XML that is being edited) and the Schema(s) on which this XML is based. The output is XML that adheres to the schemas.

Use of standard XML-Schemas is fine, although the widgets on the generated editor can be tweaked by annotations/appinfo sections in the XML-Schema.

In short, XEF should allow you to create a Eclipse editor for any piece of XML without writing Eclipse GUI code, as long as the XML is defined by a Schema.

XEF itself is written using the Eclipse Forms-based GUI framework. A modern-looking GUI toolkit available from Eclipse. The plugin.xml editor, part of the PDE is also built using this framework.

## What does it looks like?

Note that since the XEF framework started its life as the Curry Policy Editor, there currently are some small remnants of Policy in XEF. These are quite superficial and will be removed.

The following screenshot is based on parts of this schema: example_logging.xsd
You can see that this editor edits an XML file that contains 2 Main elements: `example:audit` and `example:logging`. The logging element has a few sub-elements. On the right-hand panel the attribute values (and tag text values) of the currently selected element (example:FileLogger can be edited. E.g. the 'Echo to Screen' attribute is based on the following attribute schema definition:

    <xs:attribute name="echoToScreen" type="xs:boolean">
      <xs:annotation>
        <xs:documentation>Also echo the log information to the screen.</xs:documentation>
        <xs:appinfo>
          <xef:displayName>Echo to Screen</xef:displayName>
        </xs:appinfo>
      </xs:annotation>
    </xs:attribute>

The main thing that defines the 'Echo to Screen' widgets is the fact that this is a xs:boolean. The tool tip is taken from the `xs:documentation` (a standard annotation) and the displayname is taken from the xs:appinfo. Without the appinfo section the name of the variable would just have been echoToScreen. You also see a button with a 'D' on it to the right of the element. When selected it means that the default value of this attribute will be used and hence the attribute will not be set in the resulting XML. If the schema has the default attribute, its value will be displayed (in grey, as can be seen at the 'Refresh Rate' attribute).

This is just a small example of what is possible with XEF. Many more widget types XML-Schema types are supported. Many other tweaks are supported. This is all documented in the XEF reference section. From a high level the following features are supported:

- Simple Types and Complex Types
- Enumerated types
- Choice and Sequence sections
- XML documents with embedded content that is based off multiple schemas
- The registration of a Schema Catalogue, which makes it possible to add new sub-elements to an XML file (e.g. 'Add Policy').
- Element-level xs:documentation (plain text or HTML) visible in a help view. Attribute-level xs:documentation renders into tooltips.
- The ability to provide ways to choose from options based on the current context. E.g. the target of a routing policy must come from the available containers. This information is obtained through callbacks.

## How about the XML editor in WTP?

WTP contains a very nice text-based XML editor which does things like Intellisense, Autocompletion and Syntax coloring. XEF will use this editor for the XML-text-editing tab of its editor. Currently it doesnt use it yet, but this will be done.

## How to use:

Although the XEF editor can be associated with a file extension, probably the best way to use is it through the {@link org.eclipse.stp.ui.xef.editor.XMLProviderEditorInput} editor Input implementation. This editor input has the following Constructor: {@link org.eclipse.stp.ui.xef.editor.XMLProviderEditorInput#XMLProviderEditorInput(String,IXMLProvider,ISchemaProvider,IContextProvider)} An {@link org.eclipse.stp.xef.IXMLProvider} is an interface that can get and set the value of an object as XML. So regardless of how your data is internally represented, as long as it is possible to define `getXML()` and `setXML()` operations on it, you can edit it with the XEF editor. Interesting implementations of IXMLProvider are:

- {@link org.eclipse.stp.xef.XPathXMLProvider} - An XML provider for a section of an Ifile defined as an XPath. It can essentially edit a portion of an XML file while leaving the rest alone.
- {@link org.eclipse.stp.xef.MultiXMLProvider} – Is an XML provider that will allow the editing of multiple IXMLProviders in one go. It will compute the intersection of the XML elements present across all the IXMLProviders passed in and provide editing on that. The `setXML()` call will merge the XML back with the original IXMLProviders. As an example it can be used to edit or add policies to a number of services in one go.

The ISchemaProvider provides a callback mechanism that will list all the schemas of elements that can be added to the currently edited XML. E.g. and 'Add Policy' button will bring up a dialog containing all the policies the user can add to the current list of policies. The dialog is populated through this callback. The IContextProvider provides information to the editor based on the current context. The EditorInput is obviously oblivious to how implementations of these interfaces are obtained, But one way to do this is through the Eclipse Adapter pattern, by providing an org.eclipse.core.runtime.IAdapterFactory that can do the adaptation of objects exposed through the XEF editor. Once you have the XMLProviderEditorInput, the editor can be opened with: {@link org.eclipse.ui.ide.IDE#openEditor(workbenchPage, xmlProviderEditorInput, XefConstants.XEF_EDITOR)}

## Schema Extensions

Additional elements in the schema (in appinfo sections) can influence the appearance of elements in the GUI. These are defined in the folling XML-Schemas: http://schemas.eclipse.org/stp/xsd/2006/05/xef and http://schemas.eclipse.org/stp/xsd/2006/05/xef/gui.