Editor Configuration
structured source editing (sse) component
Date Revision info
9/07/2005 Initial contribution
 
Overview
 

One main goal of the Structured Source editing framework is to provide a way for clients to extend the Structured Text Editor without having to subclass the editor.
Part of this goal is achieved through the editor configuration extension point. The editor configuration extension point allows clients to customize the Structured Text Editor for different/new content types.

The Structured Text editor is designed to handle different types of "structured" content types as input, such as XML, HTML, JSP, CSS. This includes the ability to change content types on-the-fly. For example, editing an HTML document, then deciding to change it to JSP by performing Save As.. *.jsp. The different types of configurations clients can contribute include:

  • Outline view configuration - configure behaviour in the outline view (elements to display, menu items, etc)
  • Properties view configuration - configure behaviour in the properties view (properties to display, menu items, etc)
  • Structured text viewer configuration - configure behaviour in the editor (content assist, syntax highlighting, hyperlink navigation, etc)

Through an extension point, clients can declare their configuration and the associated content type or editor id.

Use Cases
 

Examples of editors that could use editorConfiguration:

  • DTD editor

    Client creates their own DTD content type and would like to edit DTD with Structured Text Editor.
    Clients would like to be able to extend the following:

    • outline view
    • syntax highlighting, source validation, hover help
  • XML editor

    Client creates their own XML content type and would like to edit XML with Structured Text Editor.
    Clients would like to be able to extend the following:

    • outline view
    • properties view
    • content assist, syntax highlighting, source validation, and many other viewer configurations
  • WSDL editor

    Client creates their own WSDL content type and would like to edit WSDL with Structured Text Editor. Since the WSDL content type extends the XML content type, the WSDL editor should pick up all editor functionality for XML content type.
    Clients would like to be able to extend the following:

    • outline view
    • properties view
    • hyperlink navigation
  • JSP editor

    Client creates their own JSP content type and would like to edit JSP with Structured Text Editor. Since a JSP file can contain different parts of different content types (such as HTML tags, JSP Java scriptlets) JSP editor should utlilize some customizations from other content types.
    Clients would like to be able to extend the following:

    • outline view
    • properties view
    • content assist, syntax highlighting, source validation, and many other viewer configurations
Editor Configuration Extension Point
  org.eclipse.wst.sse.ui.editorConfiguration

<!ELEMENT extension (sourceViewerConfiguration* , contentOutlineConfiguration* , propertySheetConfiguration* , provisionalConfiguration* , provisionalDefinition*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT sourceViewerConfiguration EMPTY>

<!ATTLIST sourceViewerConfiguration

target CDATA #REQUIRED

class  CDATA #REQUIRED>

Defines the source viewer configuration, affecting syntax highlighting, content assist, hover help, and more in the current editor.


  • target - A string defining when to use this extension, either an editor or content type id. Multiple targets may be given as a comma delimited value.
  • class - Must subclass org.eclipse.wst.sse.ui.StructuredTextViewerConfiguration

<!ELEMENT contentOutlineConfiguration EMPTY>

<!ATTLIST contentOutlineConfiguration

target CDATA #REQUIRED

class  CDATA #REQUIRED>

Defines how the current editor's input maps to elements with in a Tree control, as well as selection filtering, toolbar and menu contributions, etc in the Outline view.


  • target - A string defining when to use this extension, either an editor or content type id. Multiple targets may be given as a comma delimited value.
  • class - Must subclass org.eclipse.wst.sse.ui.views.contentoutline.ContentOutlineConfiguration

<!ELEMENT propertySheetConfiguration EMPTY>

<!ATTLIST propertySheetConfiguration

target CDATA #REQUIRED

class  CDATA #REQUIRED>

Defines how the current editor's input maps to properties in a Table control, as well as toolbar contributions, etc in the Properties view.


  • target - A string defining when to use this extension, either an editor or content type id. Multiple targets may be given as a comma delimited value.
  • class - Must subclass org.eclipse.wst.sse.ui.views.properties.PropertySheetConfiguration

<extension point="org.eclipse.wst.sse.ui.editorConfiguration">
<!-- associating a source viewer configuration to an input's content type-->
	<sourceViewerConfiguration
          class="org.eclipse.wst.html.ui.StructuredTextViewerConfigurationHTML"
          target="org.eclipse.wst.html.core.htmlsource"/>

<!-- associating an outline configuration to an input's content type -->
	<contentOutlineConfiguration
          class="org.eclipse.wst.sse.xml.ui.views.contentoutline.XMLContentOutlineConfiguration"
          target="org.eclipse.core.runtime.xml"/>
<!-- associating a property sheet configuration to multiple content types -->
	<propertySheetConfiguration
          class="org.eclipse.wst.xml.ui.views.properties.XMLPropertySheetConfiguration"
          target="org.eclipse.wst.sse.contenttype.xml, org.eclipse.wst.html.core.htmlsource, org.eclipse.jst.jsp.core.jspsource"/>
</extension>

Target Resolution Policy
 

Clients can target their editor configuration to either a specific content type and/or editor. In the event there are conflicts as to which configuration should be used, below is the resolution policy.

  1. configuration with matching editor id
  2. configuration with matching editor id + ".source" in multipage editors
  3. configuration with matching content type id
  4. configuration for content type's base content type
  5. default Structured Text Editor configuration

If more than one configuration is defined for an editor type or content type, the first one defined, is the first one served.

SourceViewerConfiguration
 

The structured text viewer configuration customizes various aspects of the Structured text editor. It defines syntax highlighting, content assist, and more. Clients must subclass org.eclipse.wst.sse.ui.StructuredTextViewerConfiguration to provide a custom viewer configuration for their content type. Clients contributing new configuration for new content types can utilize an existing configuration. They can subclass the existing configuration to build on top if it. Or they can create a new instance of the existing configuration in their configuration, and call the methods within it. The StructuredTextViewerConfigurationJSP, for example, creates new instances of the StructuredTextViewerConfigurationHTML, StructuredTextViewerConfigurationXML, JavaSourceViewerConfiguration and retrieves their processors to be reused in JSP content.

ContentOutlineConfiguration
 

The outline view configuration customizes the editor's outline view. It defines how the current editor's input maps to elements in a Tree control, as well as selection filtering, toolbar/menu contributions, etc. Clients must subclass org.eclipse.wst.sse.ui.views.contentoutline.ContentOutlineConfiguration to provide a custom outline view for their content type.

PropertySheetConfiguration
 

The properties view configuration customizes the editor's properties view. It defines how the current editor's input maps to a list of properties in a Table control, as well as toolbar/menu contributions, etc. Clients must subclass org.eclipse.wst.sse.ui.views.properties.PropertySheetConfiguration to provide a custom properties view for their content type.


Migration information from earlier revisions can be found here.