1. 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

2. 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 3. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Introduction What is WTP? Where does SSE fit in? 4. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 5. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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. Its 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 6. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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: 7. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Text Editors, editor inputs, and document providers CVS File URL Editor Inputs Text Editor Correct Document Provider Text Document 8. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Text selection Represents a span of text from the document Very basic, but very useful 9. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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. 10. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 An Anatomy of Text Editors 11. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 A tour of SSE and the XML DOM 12. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 13. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 14. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 15. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 16. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 17. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Node Adapters Created by INodeAdapterFactory, registered in the IStructuredModel's FactoryRegistry 18. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 19. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 20. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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. 21. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Contributing Actions and Commands 22. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 23. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 24. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 User Created Templates Users create templates via Templates preference page 25. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 26. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 27. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 Some more advanced features And none of it by subclassing St r uct ur edText Edi t or 28. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 29. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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! 30. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 31. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 32. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 33. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Example of EditorConfiguration 34. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 35. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 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 36. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 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 37. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 http://www.eclipse.org/webtools/wst/components/sse/tutorials/source-validation.html for more information. 38. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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. 39. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Limitations of this approach No per-language functionality without overall enablement. 40. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 Be careful about leaving any text editor functionality out. Users hate that. 41. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Getting information out of the editor 42. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 43. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Event Notification IDocumentListener IStructuredDocumentListener Adapter Notification All equally valid 44. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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/actionco ntributor/debugstatusfields trace option in Eclipse Application Launch configuration. Double-click on bracketed selection range in status bar while editor is open. 45. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. 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 46. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Examples 47. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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 48. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 Bug reports, feature requests, code and documentation contributions are always welcome. 49. Building the XML Editor you've always wanted | Copyright IBM Corp., 2006-2009. All rights reserved; made available under the EPL v1.0 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.