Building the XML Editor you've always wanted

Copyright © IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 | March 24, 2009
Building the XML Editor you've always wanted
Based on materials prepared with David Williams and Amy Wu
Nitin Dahyabhai, IBM Rational
Konstantin Kommisarchik, Oracle Corp.
Nick Sandonato, IBM Rational

Building the XML Editor you've always wanted | Copyright © IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0
Agenda and Topics to Cover
• Introduction
• Eclipse Platform concepts
• A tour of WTP's SSE and XML DOM
• Adding functionality into the editor
• Getting information out of the editor
• Debugging Tools and Tips
• Examples
• Questions and your code

Introduction
• What is WTP?
• Where does SSE fit in?

Eclipse Platform Concepts
• Content types
• Text documents, partitions, and partitionings
• Text Editors, text selection, editor inputs, and document
providers
• Markers, positions, and annotations
• An Anatomy of Text Editors

Eclipse Content Types
• Eclipse base documentation:
 A central content type catalog for Eclipse
• Type of content, not specific to files
• Beyond file type via file extensions
 User settable “family” of file types
 Can be influenced by actual contents of file
• Determines “encoding rules” through IContentDescription
• Can associate editors, validators, etc.
• Content Types are hierarchical, a fact which should not be
discounted. It’s common to define your own contentType, say
for a specialized form of XML, based on some specific DTD,
and then associate it with your editor

Text documents, partitions, and partitionings
• Documents are divided into partitions. The different
schemes for doing this are called partitionings.
• Here are two such partitionings of the same XML
source:

Text Editors, editor inputs, and document providers
CVS
File
URL
Editor
Inputs
Text Editor
Correct Document Provider Text Document

Text selection
• Represents a span of text from the document
• Very basic, but very useful

Positions, annotations, and markers
• Positions represent sections of a document by an offset
and length
• Positions are updated automatically when the document
is modified so that they still point to the same text, as
much as possible.
• Annotations indicate something special about a part of
the document, such as a spelling mistake.
• Markers do the same thing, but for files in the
workspace.

An Anatomy of Text Editors

A tour of SSE and the XML DOM

Structured Documents
• Composed of a series of Document Regions
• Document Regions are each composed of Text Regions
• Text Regions represent specific syntactic parts of the
language
Structured Document
Document Region Document Region Document Region
Doc
Region
Document Region Document Region

Structured Models
• Always contain a Structured Document
• Maps text document offset to generic IndexedRegion
• For XML, the IndexedRegion is also a W3C DOM Node
• Knows the specific content type for which it was created
• Usually shared

Sharing your Structured Model
• Accessed with a Model Manager through
StructuredModelManager.getModelManager();
• The SSE ModelManager uses reference counts
• getModelForEdit(*)/getModelForRead(*) to connect
• releaseFromEdit()/releaseFromRead() to disconnect
• Always use try {get} ..finally {release} – consider this a
resource to be managed just like a native object
• For thread control, use model.aboutToChange() and
model.changed(); to bracket more than one
modification
• When a model is fully released, it is disposed of and no
longer valid

IDOMModel
• Provisional subinterface that returns the W3C
Document
• Changes to the Structured Model and Structured
Document are synchronized in both directions
• The source parser being used is very fault tolerant

SSE's XML DOM implementation
• Recommend using Standard DOM APIs (if and when possible)
• Mostly compliant with DOM Levels 1 and 2, plus Traversal and
Ranges. Greater compliance and Level 3 are being investigated.
• Intentional deviations from the XML Recommendations:
 We maintain existing EOLs (XML Spec says to convert all,
even CR-LF, to LF)
 Unless reformatted, we preserve white-space, resulting in
many white-space-only Text Nodes
 Contains setters in more places
• Unintentional deviations from the XML Recommendations:
 We “mis-use” PI for XMLDecl

Node Adapters
• Created by INodeAdapterFactory, registered in the
IStructuredModel's FactoryRegistry

Hybrid Selection
• IEditorActionDelegates operate on ISelection
• StructuredTextEditor provides a selection object combining:
 ITextSelection
 IStructuredSelection
• ITextSelection - current text selection (just as in other
ITextEditors)
• IStructuredSelection - corresponding model objects for the
selected text positions, object types vary depending on the
language being edited

More on selection
• When working with an XML file, the selected objects are
DOM Nodes
• In WTP 3.1, this can narrow down to a single Attr Node
• Your IEditorActionDelegates have access to the
selected DOM Nodes automatically

Adding function into the editor
• Without extending the editor!
 Content Models: DTDs, XML Schema, JSP Custom Tag
Libraries
 XML Catalog
• Custom editors are no substitute for well designed
documents (and languages) – with their legal content
well defined. A good grammar helps every editor.

Contributing Actions and Commands

Additional Information on Actions in Editors
• Eclipse Article:
 http://www.eclipse.org/articles/Article-action-contribution/Contributi
• Help Documentation:
 org.eclipse.ui.editorActions extension point schema
 org.eclipse.ui.popupMenus extension point schema

Improving the Text Editor Experience
• Templates
 Pieces of text or code which help the user enter reoccurring
patterns into a text editor
 Invoked via content assist for predetermined contexts

User Created Templates
• Users create templates via Templates preference page

Contributing Additional Templates
• Contribute additional templates via extension point
 org.eclipse.ui.editors.templates

• Specify
 Template pattern
 Template context

Extending the Structured Text Editor
• Start out simple
 St r uct ur edText Edi t or is a text editor
 Common editor input types are supported
 External files supported
 Syntax coloring often Just Works

• Built-in Drag and Drop
• Content Outlines
• Property Sheets
• As-you-type validation
• Designed to work well in multi-page editors
Some more advanced features
And none of it by subclassing
St r uct ur edText Edi t or

Extending the Structured Text Editor using Editor Configuration
• Customize Structured text editor for different/new
content types
 org.eclipse.wst.sse.ui.editorConfiguration

• Configurations include:
 Structured text viewer configuration
 Outline view configuration
 Properties view configuration

• Configuration class hierarchy mimics and maps to the
Content Type hierarchy

Structured Text Viewer Configuration
• Customizes various aspects of the Structured text
editor including:
 content assist
 hyperlink navigation
 autoedit
 many more!

Creating a Structured Text Viewer Configuration
• Must subclass
or g. ecl i pse. wst . sse. ui . St r uct ur edText Vi ewer Con
f i gur at i on
•
• You can utilize existing configurations:
 Subclass
 Instantiate and delegate to new instances

Existing Structured Text Viewer Configurations
• Existing Structured Text Viewer Configurations in WTP
 or g. ecl i pse. wst . xml . ui . St r uct ur edText Vi ewer Conf i g
ur at i onXML
 or g. ecl i pse. wst . ht ml . ui . St r uct ur edText Vi ewer Conf i
gur at i onHTML
 or g. ecl i pse. j st . j sp. ui . St r uct ur edText Vi ewer Conf i g
ur at i onJSP
 or g. ecl i pse. wst . css. ui . St r uct ur edText Vi ewer Conf i g
ur at i onCSS
 or g. ecl i pse. wst . dt d. ui . St r uct ur edText Vi ewer Conf i g
ur at i onDTD
 or g. ecl i pse. wst . xsd. ui . i nt er nal . edi t or . St r uct ur ed
Text Vi ewer Conf i gur at i onXSD

Source Viewer Configuration via EditorConfiguration
• Extension point:
org.eclipse.wst.sse.ui.editorConfiguration
 sourceViewerConfiguration element
•
• Specify:
 Your implementation of
StructuredTextViewerConfiguration
 Content type associated with your configuration

Example of EditorConfiguration
• <extension
point="org.eclipse.wst.sse.ui.editorConfiguration">
 <sourceViewerConfiguration
 class="org.eclipse.wst.html.ui.StructuredTextViewerConfigur
ationHTML“
 target="org.eclipse.wst.html.core.htmlsource"/>
• </extension>

Additional Information on Source Viewer Configuration
• Design Document:
 http://www.eclipse.org/webtools/wst/components/sse/designs/Ed
• Help Documentation:
 org.eclipse.wst.sse.ui.editorConfiguration extension
point schema
• JavaDoc:
 org.eclipse.jface.text.source.SourceViewerConfiguration
 All its subclasses
 org.eclipse.wst.sse.ui.StructuredTextViewerConfiguratio
n
 All its subclasses
•

Content Outline Configuration
• Customize aspects of the Outline view
 Which objects shown in the tree and their labels
 Additional pull-down and context menu contributions
 New toolbar contributions
 Key handling
 Drag and Drop support
 And more!
•
• Must subclass
or g. ecl i pse. wst . sse. ui . vi ews. cont ent out l i ne. Cont ent Out l i neC
onf i gur at i on

Property Sheet Configuration
• Customize aspects of the Properties view
 Which properties are shown for selected objects
 Additional pull-down menu and toolbar contributions
 And more!

• Only supports the classic Property Sheet for now, not
the Tabbed Property Sheet
•
• Must subclass
or g. ecl i pse. wst . sse. ui . vi ews. pr oper t i es. Pr oper t ySheet Conf i
gur at i on

• In-editor validation extension point
 org.eclipse.wst.sse.ui.sourcevalidation
•
 Validates as-you-type, in the background
 Reuses Validation component APIs
 Implement IValidator to validate entire contents of file,
associating the validator to specific content-types and
partition types
 Implement ISourceValidator from org.eclipse.wst.sse.ui
to validate specific text regions as the content is
edited

• See
http://www.eclipse.org/webtools/wst/components/sse/tutorials/source-validation.html
for more information.

Examples of Utilizing Existing Configurations
• StructuredTextViewerConfigurationWSDL subclasses
StructuredTextViewerConfigurationXML to add its
own WSDLHyperlinkDetector
•
• StructuredTextViewerConfigurationJSP creates new
instances of:
 StructuredTextViewerConfigurationHTML
 StructuredTextViewerConfigurationXML
 JavaSourceViewerConfiguration
• and retrieves their processors to be reused in JSP
content.

Limitations of this approach
•No per-language functionality without overall enablement.

Reusing the Structured Text Editor
• Start out simple – StructuredTextEditor is a text editor
after all
• Regular editor input types are supported, including
external files
• Editor Configuration is still used
• StructuredTextEditor returns adapters for many
common workbench functions
• Be careful about leaving any text editor functionality
out. Users hate that.

Getting information out of the editor

Selection Notification
• Register views as listener of the ISelectionService
 Eclipse.org Article on Using the Selection Service

• Beware selection notification loops
•
• Design Document on Selection and the
StructuredTextEditor:
 http://www.eclipse.org/webtools/wst/components/sse/designs/EditorSelection.html
•

Event Notification
• IDocumentListener
• IStructuredDocumentListener
• Adapter Notification
• All equally valid

Tools and Debugging Tips – Editor Information Dialog
• Presents read-only information
about the editor and its
contents.
•
• Enable
org.eclipse.wst.sse.ui/actionco
ntributor/debugstatusfields
trace option in Eclipse
Application Launch
configuration.
•
• Double-click on bracketed
selection range in status bar
while editor is open.

Tools and Debugging Tips – Editor Information Dialog
• Selection information
• IDocument and IDocumentProvider
implementations in use
• IEditorInput class
• Content-Type reported by
IStructuredModel
• Partitions according to each
partitioning
• Annotations and their properties
• Document and Text Regions
• Adapters for INodeNotifiers

Examples

Get involved!
• Newsgroup: news://news.eclipse.org/eclipse.webtools
•
• SSE home page:
http://www.eclipse.org/webtools/wst/components/sse/overview.html
•
• Bugzilla: http://bugs.eclipse.org/
 Product: Web Tools
•
• Bug Day: http://wiki.eclipse.org/BugDay
 Community outreach

Bug reports, feature requests, code and
documentation contributions are always welcome.

Legal Notices
 Copyright © IBM Corp., 2006-2008. All rights reserved. Source code in this presentation is made
available under the EPL, v1.0, remainder of the presentation is licensed under Creative
Commons Att. Nc Nd 2.5 license.

 IBM and the IBM logo are trademarks or registered trademarks of IBM Corporation, in the United
States, other countries or both.

 Rational and the Rational logo are trademarks or registered trademarks of International Business
Machines Corporation in the United States, other countries or both.

 Java and all Java-based marks, among others, are trademarks or registered trademarks of Sun
Microsystems in the United States, other countries or both.

 Eclipse and the Eclipse logo are trademarks of Eclipse Foundation, Inc.

 Other company, product and service names may be trademarks or service marks of others.

 THE INFORMATION DISCUSSED IN THIS PRESENTATION IS PROVIDED FOR
INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE
COMPLETENESS AND ACCURACY OF THE INFORMATION, IT IS PROVIDED "AS IS"
WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, AND IBM SHALL NOT BE
RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE
RELATED TO, SUCH INFORMATION. ANY INFORMATION CONCERNING IBM'S
PRODUCT PLANS OR STRATEGY IS SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.
•

Building the XML Editor you've always wanted

More Related Content

What's hot

Similar to Building the XML Editor you've always wanted

Building the XML Editor you've always wanted

Editor's Notes