copyright © ibm corp., 2006-2008. all rights reserved; made available under the epl v1.0 | march...

Copyright © IBM Corp., 2006-2008. All rights reserved; made available under the EPL v1.0 | March 17, 2008

Extending the XML and SSE editors from the Web Tools Platform Project

Nitin Dahyabhai

IBM Rational Software

[email protected]

Based on materials prepared with David Williams and Amy Wu

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., 2006-2008. All rights reserved; made available under the EPL v1.0

Agenda and Topics to Cover• Introduction• An Anatomy of Text Editors• Extending Text Editors• Eclipse Content Types• Improving the Text Editing Experience• Architecture of Structured Source Editing (SSE) Models

Structured Models Structured Documents

• Improving the Structured Text Editing Experience• Extending the Structured Text Editor

Dual Selection Editor Configuration

• Reusing the Structured Text Editor• Debugging Tools and Tips• Examples and Exercises• Questions and your code


Introduction

• What is WTP Source Editing?• Where does SSE fit in?


Architecture – high level

• Purpose of Structured Source Editing (SSE) is intended to be a thin layer on top of Eclipse text infrastructure

Aides some things Some things just different (or better?!)

Especially for “mark up” type languages Especially for “mixed content”


An Anatomy of Text Editors


An Anatomy of Text Editors

Document providers take the editor inputs and allow text editors to open and save the document contents, as well as react to changes in the input.

Text IDocument


Extending Text Editors

• Eclipse platform framework provides extension points to contribute actions

org.eclipse.ui.editorActions - contribute actions to editor menu bar and toolbar

org.eclipse.ui.popupMenus - contribute actions to context menu


Action class

• Implement org.eclipse.ui.IEditorActionDelegate to contribute action to editor

public class MyActionDelegate implements IEditorActionDelegate {public void setActiveEditor(IAction action, IEditorPart targetEditor) {

// TODO Auto-generated method stub}public void run(IAction action) {

// TODO Auto-generated method stub}public void selectionChanged(IAction action, ISelection selection) {

// TODO Auto-generated method stub}

}


Action Targets


Action targetID

• Need to specify "targetID" where your action will be placed

• org.eclipse.ui.editorActions targetID is the editor id of the editor you are contributing your

action to.

• org.eclipse.ui.popupMenus targetID is the context menu id of the editor you are

contributing your action to Structured Text Editors have some targetID's already set up in

various popup menus for clients to use Structured Text Editors' popup menu ids are generated in the

following format: [content type].[editor type keyword].[place to contribute keyword]


But wait, what are content types?


Eclipse Content Types

• Eclipse base documentation:

A central content type catalog for Eclipse • 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


Possible Content Types/Editor Types/Popup Menus

• Possible content types: org.eclipse.core.runtime.xml org.eclipse.wst.html.core.htmlsource org.eclipse.jst.jsp.core.jspsource org.eclipse.wst.css.core.csssource org.eclipse.wst.dtd.core.dtdsource

• Possible editor types: source - source page editor

• Possible places to contribute: EditorContext - editor popup menu RulerContext - editor vertical ruler popup menu OutlineContext - outline view popup menu


Action targetID Examples• Contribute action to the editor context menu of the XML editor

targetID="org.eclipse.core.runtime.xml.source.EditorContext“

• Contribute action to the vertical ruler context menu of the HTML editor

targetID="org.eclipse.wst.html.core.htmlsource.source.RulerContext“

• Contribute action to the outline view’s context menu of the DTD editor

targetID="org.eclipse.wst.dtd.core.dtdsource.source.OutlineContext“

• Contribute action to menu bar/toolbar for the JSP editor targetID="org.eclipse.jst.jsp.core.jspsource.source“

• Contribute action to menu bar/toolbar for the CSS editor targetID=“org.eclipse.wst.css.core.csssource.source”


Additional Information on Actions in Editors

• Eclipse Article:http://www.eclipse.org/articles/Article-action-contribution/Contributing%20Actions%20to%20the%20Eclipse%20Workbench.html

• Help Documentation:org.eclipse.ui.editorActions extension point schema

org.eclipse.ui.popupMenus extension point schema


Improving the Text Editor Experience

• TemplatesPieces of text or code which help the user enter reoccurring patterns into a text editorInvoked 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


The Snippets View

The Snippets view shows a palette of reusable text snippets that can be dragged and dropped into all text editors.

Improving the Text Editor Experience


User Created Snippets

• Users can create and organize their own snippets using the Customize dialog, or just copying and pasting text into the view

• Variables can be created in the snippet for the user to fill in when the snippet is dropped into an editor

• Drawers can be automatically shown and hidden based on the active editor’s Eclipse Content Type

• Snippets are not tied to specific languages or their Content Assist support


Contributing Additional Snippets

• Contribute additional drawers and snippets via extension point

org.eclipse.wst.common.snippets.SnippetContributions

• Plug-in developers can do all of this and more: Tailored dialog when dropped into SSE text editors Custom behavior when double-clicked

Snippets component home page: http://www.eclipse.org/webtools/wst/components/common/overview/snippets/overview.html


Architecture of SSE Models

• Partition Types• Structured Documents

Structured Document Events Structured Document Regions

• Structured Models (focusing on DOM models) Structured Model Manager Adapters and notifications


Partition types

1. Partitions divide a text document into different areas, for example Java source code and JavaDoc comments.

2. There is no 2, a language provider can partition their documents any way they want, as many ways as they want using different partitioners.


Structured Documents

• Builds on the standard text IDocument• Uses partitions to map functionality to function

providers• Further divides the text of a document into document

regions and syntax-level language-specific text regions.


Structured Models

• Accessed with a Model Manager through StructuredModelManager.getModelManager();

• Every Structured Model contains a Structured Document• Structured Models are usually “shared”, a “get” will create one if one

doesn’t already exist• Models are gotten “for Read” or “for Edit” – ‘edit’ means you are

interested in saving changes• Always use try {get} ..finally {release} – consider this a resource to

be managed just like a native object• For XML, HTML, and JSP models, IDOMModel.getDocument()

gives W3C DOM Document• Changes in the Model and Document are synchronized in both

directions.• For thread control, use model.aboutToChange() and

model.changed(); to bracket more than one modification


Changing the Text Document by Changing the text1. Use IDocument APIs

2. There’s no 2, again, although you can also supply a “change source”.


Changing the Text Document by Changing the DOM1. Use Standard DOM APIs (if and when possible)

Mostly compliant with DOM Levels 1 and 2

2. Note some 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 We “mis-use” PI for XMLDecl


Improving the Structured Text Editing Experience• 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


Dual Selection in Structured Text Editors

• IEditorActionDelegates operate on ISelection, and StructuredTextEditor provides an ISelection combining:

ITextSelection IStructuredSelection

• ITextSelection - current text selection (just as in other ITextEditors)

Used by new matching bracket navigation

• IStructuredSelection - corresponding model objects for the selected text positions, object types vary depending on the language being edited

Used by new sibling navigation


Working with Selection

• Register views as listener of the ISelectionServiceEclipse.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


Extending the Structured Text Editor

Start out simple StructuredTextEditor 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

editorsBut wait,

there

’s more

!

Some more advanced features

And none of it by subclassing StructuredTextEditor


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 org.eclipse.wst.sse.ui.StructuredTextViewerConfiguration

• You can utilize existing configurations: Subclass Instantiate and delegate to new instances


Existing Structured Text Viewer Configurations

• Existing Structured Text Viewer Configurations in WTP org.eclipse.wst.xml.ui.StructuredTextViewerConfigurationXML org.eclipse.wst.html.ui.StructuredTextViewerConfigurationHTML org.eclipse.jst.jsp.ui.StructuredTextViewerConfigurationJSP org.eclipse.wst.css.ui.StructuredTextViewerConfigurationCSS org.eclipse.wst.dtd.ui.StructuredTextViewerConfigurationDTD org.eclipse.wst.xsd.ui.internal.editor.StructuredTextViewerCo

nfigurationXSD org.eclipse.wst.wsdl.ui.internal.StructuredTextViewerConfigur

ationWSDL


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

<sourceViewerConfigurationclass="org.eclipse.wst.html.ui.StructuredTextViewerConfigurationHTML“

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/EditorConfiguration.html

• 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.StructuredTextViewerConfiguration 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 org.eclipse.wst.sse.ui.views.contentoutline.ContentOutlineConfiguration


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 org.eclipse.wst.sse.ui.views.properties.PropertySheetConfiguration



In-editor validation extension pointorg.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


Tools and Debugging Tips – Editor Information Dialog

• Presents read-only information about the editor and its contents.

• Enable org.eclipse.wst.sse.ui/actioncontributor/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


Exercises

• Theme: Improve the users’ experience for editing web.xml files

• How to proceed: Start with and examine either the Deployment Descriptor Editor Plug-in Project template or step through the Extending the XML Editor Cheat Sheets to create a skeleton for adding your own features

• If we have time left over, feel free to ask about or show your “real world” 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.orgProduct: Web Tools

• Bug Day: http://wiki.eclipse.org/BugDayCommunity 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.

copyright © ibm corp., 2006-2008. all rights reserved; made available under the epl v1.0 | march...

Documents

sse editors

wtp project copyright

epl v1

text idocument slide

extending th

wtp source editing

code slide

mixed content slide