Copyright © IBM Corp., 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 Based on materials prepared with David Williams and Amy Wu

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Introduction What is WTP Source Editing? Where does SSE fit in?

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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”

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 An Anatomy of Text Editors

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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 the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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 }

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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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]

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 But wait, what are content types?

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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.RulerContex t“ 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”

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Additional Information on Actions in Editors Eclipse Article: contribution/Contributing%20Actions%20to%20the%20Eclip se%20Workbench.html Help Documentation: org.eclipse.ui.editorActions extension point schema org.eclipse.ui.popupMenus extension point schema

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 User Created Templates Users create templates via Templates preference page

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Contributing Additional Templates Contribute additional templates via extension point  org.eclipse.ui.editors.templates Specify  Template pattern  Template context

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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:

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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.

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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.

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Changing the Text Document by Changing the text 1.Use IDocument APIs 2.There’s no 2, again, although you can also supply a “change source”.

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Changing the Text Document by Changing the DOM 1.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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Improving the Structured Text Editing Experience Without extending the editor!  Content Models: DTDs, XML Schema, JSP Custom Tag Libraries  XML Catalog XML Catalog Custom editors are no substitute for well designed documents (and languages) – with their legal content well defined

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Working with Selection Register views as listener of the ISelectionService Eclipse.org Article on Using the Selection ServiceUsing the Selection Service Beware selection notification loops Design Document on Selection and the StructuredTextEditor:

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Extending the Structured Text Editor Built-in Drag and Drop Content Outlines Property Sheets As-you-type validation Designed to work well in multi-page editors But wait, there’s more! Some more advanced features And none of it by subclassing StructuredTextEditor

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Structured Text Viewer Configuration Customizes various aspects of the Structured text editor including:  content assist  hyperlink navigation  autoedit  many more!

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Creating a Structured Text Viewer Configuration Must subclass org.eclipse.wst.sse.ui.StructuredTextViewerConfi guration You can utilize existing configurations:  Subclass  Instantiate and delegate to new instances

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Existing Structured Text Viewer Configurations Existing Structured Text Viewer Configurations in WTP  org.eclipse.wst.xml.ui.StructuredTextViewerConfigurat ionXML  org.eclipse.wst.html.ui.StructuredTextViewerConfigura tionHTML  org.eclipse.jst.jsp.ui.StructuredTextViewerConfigurat ionJSP  org.eclipse.wst.css.ui.StructuredTextViewerConfigurat ionCSS  org.eclipse.wst.dtd.ui.StructuredTextViewerConfigurat ionDTD  org.eclipse.wst.xsd.ui.internal.editor.StructuredText ViewerConfigurationXSD  org.eclipse.wst.wsdl.ui.internal.StructuredTextViewer ConfigurationWSDL

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Example of EditorConfiguration <sourceViewerConfiguration class=" org.eclipse.wst.html.ui.StructuredTextViewerConfigurationHTML “ target=" org.eclipse.wst.html.core.htmlsource "/>

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Additional Information on Source Viewer Configuration Design Document: ditorConfiguration.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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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.ContentOutlineCo nfiguration

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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.PropertySheetConfigu ration

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Extending the Structured Text Editor 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 validation.html for more information. validation.html

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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.

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Limitations of this approach No per-language functionality without overall enablement.

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Tools and Debugging Tips – Editor Information Dialog Presents read-only information about the editor and its contents. Enable org.eclipse.wst.sse.ui/actioncontr ibutor/debugstatusfields trace option in Eclipse Application Launch configuration. Double-click on bracketed selection range in status bar while editor is open.

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 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

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Get involved! Newsgroup: news://news.eclipse.org/eclipse.webtoolsnews://news.eclipse.org/eclipse.webtools SSE home page: Bugzilla: Product: Web Tools Bug Day: Community outreach

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Bug reports, feature requests, code and documentation contributions are always welcome.

Extending the XML and SSE editors from the WTP Project | Copyright © IBM Corp., All rights reserved; made available under the EPL v1.0 Legal Notices  Copyright © IBM Corp., 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.