Structured Source Editing Evaluation Guide

1.0 Introduction

Structured Source Editors (SSE) can be used to edit XML, HTML, XHTML, CSS, DTD, client-side JavaScript, and JSP 1.1, 1.2, and 2.0 with Java or server-side JavaScript. They are intended to provide all of the advanced features that Eclipse users appreciate in their editors: content assist, customizable highlighting, as-you-type validation, smart editing, integration with outline and property views and much much more.

In addition to the end-user features, the SSE editors are intended to be easy for others to re-use as the source page in multipage editors. One obvious example is as the source page of a WYSIWYG HTML editor. Programmatic interaction with the text model can be accomplished with standard Eclipse text document APIs (e.g. replace) or through standard DOM APIs. We provide a custom DOM implementation that tolerates ill-formed text and that allows for easy integration with other models.

An additional component provided is the Snippets view. This provides a type of "clip book" where plug-in providers and end-users can store their favorite bits of code to drag-and-drop into an editor.

The code in this initial proposed contribution is a snapshot "midstream" of our move to Eclipse 3.0. There are many bugs and much more to be done integrating with functionality provided in the base Eclipse text infrastructure. However, there's plenty to try out already. So give it a spin, and let us know what you like and don't like.

2.0 Getting Started

Nothing special is needed to get started, just start editing an XML, HTML, CSS, DTD, JavaScript, or JSP file. Referenced DTDs, Schemas, and tag libraries will be loaded and used to provide content assist and fill the Properties view. Note that to enjoy the Java editing integration while editing JSPs, the JSP file will need to be in a Web project or a Java project with the Build Path properly set with a server's library jars.

3.0 Quick Tour

Hopefully all the introductory "standard" editing features would be discoverable by anyone familiar with Eclipse's other editors. Therefore, we've just listed basic features in the following tables. Later in this section we've collected some "new and noteworthy" notes we've written while moving to Eclipse 3.0.

Overview of editing features, compared with Eclipse 3.0's Java Editor:

CSS DTD JavaScript
Highlighting Y Y Y Y Y Y Y
Content Assist Y Y Y Y Y N Y
Parameter/Attribute Hints Y Y Y Y N - N
Formatter Y Y Y Y Y N N
Structured Selection Y Y Y Y Y Y N
Hover Info Y Y Y Y N N Y
Smart Insert Y Y Y Y N N N
Open Selection Y Y Y Y N N N
Find Element Y Y Y Y N N N
Validating as-you-type Y Y Y Y P? N N
Delimiter Matching Y Y Y Y Y Y Y
Refactoring Participation Y - Y P? - - N
Search Participation Y P? Y P? N N N
Quick Fix & Quick Assist Y Y Y Y N? N N
Property Sheet Y Y Y Y Y N N
Outline View Y Y Y Y Y Y Y
Quick Outline Y N N N N N N
Text Folding Y P P P N N N
Task Tags Y Y Y Y Y Y N

Editing features within the mixed content of JSP files:

JSP Custom Tags HTML&XML Client-side JavaScript CSS Server-side Java Server-side JavaScript JSP Expression Language (EL)
Highlighting Y Y Y Y Y Y Y P
Content Assist Y Y Y Y Y Y Y P
Validating as-you-type Y Y Y N N Y N ?

Recently added editing functions, views, and JDT integration

Configurable Go To Next/Previous Annotation The source editor's Go To Next / Previous Error tool bar buttons have been replaced by configurable Go To Next / Previous Annotation drop-down style buttons where you can choose which annotations are considered while stepping:

These actions are also present on the Navigate menu

Outline view can not follow caret The Outline views now have a toggle option on their toolbars to control synchronization with the cursor in the source editors:

Context information for attributes A popup with information about attributes for an element is now available (invoked via ctrl+shift+space). The attributes which are already there show up in bold, and required attributes show up with an *:

Background Jobs and Progress View For a consistent "look and feel" we are taking advantage of the new-to-R3 background "Job" class and Progress View for loading content models (instead of having our own thread, and using status indicator as we did previously).

Java HoverInfo Information about symbols within Java code sections will be shown in its HoverInfo.

Java code as-you-type validation The JSP editor now provides for dynamic syntax checking of Java code sections.

Improved debugging support (JSR-045) Breakpoints set within the JSP editor can now be triggered in JSR-045 compatible servers. Apache Tomcat versions 5.0.2, 5.0.12, 5.0.16, and 5.0.25 have been successfully tested. Details are discussed here.

This makes use of the SSE Breakpoint Provider extension API allowing for the setting of breakpoints for use in other scenarios such as client-side JavaScript and XSL transformation debugging.

Conditional breakpoints with JSR-045 debugging

The JSP editor supports setting conditional breakpoints with JSR-045 compatible servers. This is done using the vertical ruler's context menu.

JSP editor ruler context menu

Note: this requires additional entries to be made on the JSP project's classpath. See Eclipse bug 51348 for details.

breakpoint properties dialog

XML Comment and Uncomment

Comment and Uncomment from the Editor pulldown menu can be used to comment each line in a block of selected text in the XML Editor. If no text is selected, the current line is commented.

XML Add Block Comment and Remove Block Comment

Add Block Comment and Remove Block Comment from the Editor pulldown menu can be used to comment all elements in a block of selected text in the XML Editor. If no text is selected, the current element is commented.

Quick Fix and Quick Assist Quick Fix provides proposals for fixing validation errors and warnings. Quick Assist provides proposals for common tasks.

Here is a list of Quick Fix proposals currently available. More proposals will be added in future milestones.
Validation Error or Warning Quick Fix Proposals
  • remove this tag
  • convert to self-ending tag
  • insert end tag
  • remove this tag
  • remove all attributes in end tag
  • insert default attribute value from content model
  • remove this attribute
  • insert default attribute value from content model
  • remove this attribute
  • remove spaces before tag name
  • remove spaces before processing instruction
  • remove namespace in processing instruction
  • remove this element
  • local rename
  • remove this attribute
  • local rename
  • replace with default attribute value from content model
  • remove this attribute value
  • insert required attribute and default value from content model
  • quote attribute value

Local Rename is the only Quick Assist proposal in this milestone. More proposals will be added in future milestones.

Open on Hyperlink Support

In previous versions, users were able to open on/navigate to the source/declaration/referred to file of certain tag attributes by using the Open Selection menu item (shortcut key F3 by default). This support has been extended so that in addition to selecting the tag attribute and pressing F3, users are able to use a combination of pressing a modifier key (the Ctrl key by default) and their mouse to hover over the tag users want to open selection on. A hyperlink will then appear for users to click on to Open Selection.

Tag File opened
any HTML tag that contains a URI attribute (as defined by the HTML 4.01 DTD) such as the Anchor tag the file located in the URI attribute value
any JSP tag that contains a URI attribute (as defined by the JSP 1.2 Specification) such as the jsp:forward tag the file located in the URI attribute value
jsp:useBean the class referenced by the useBean action
JSP Scriptlets selected Java element's declaration
DOCTYPE Declaration the file referenced by the public/system ID
Schema location attribute the file referenced by the schema location attribute

Quick Diff Support

The Source editors are now tied into the base Quick Diff support, allowing users to see the difference between their current changes in the file from either the latest version on CVS or version on disk.

Find Occurrences

Source Editors now have the ability to find occurrences of a language element in a file.

A user can now search for an element name, attribute name, attribute value, or a Java element (in the JSP Editor). To do so, press Ctrl+Shift+A or use the menu "Source > Occurrences in File". Results will appear in the Search results view.

Find Occurrences Action

Find Occurrences Results

XML Example of "Find Occurrences"

Highlighting of matching delimiters

In addition to the previous support for highlighting matching delimiters in server-side Java code snippets and JavaScript code, delimiters can now be highlighted in XML, HTML, JSP, DTD, and CSS files.

JSP Search Support

JSP files now integrate with the Java Search functionality.

Users can now search for uses of Types, Methods, Fields, etc. in their JSP files via the Java Search Dialog. Search results show up in the Search Results view together with Java search results.

JSP Search Dialog

JSP Search Results

Quick Fix and Quick Assist

The JSP Editor now has offers Quick Fix and Quick Assist support.

When the editor cursor is in a JSP Java partition and assistance is available, you may press Ctrl+1 to launch Quick Fix and Quick Assist.

Launch Quick Assist

Local Rename is one of the Quick Assist proposals which lets you rename a Java variable across multiple JSP Java partitions.

Local Rename

Task Tags

When a file of a supported content type is built, its comments will be searched for Task Tags and corresponding tasks in the Tasks view automatically created.

Add more to Snippets

The Add to Snippets context menu action previously available only in the SSE editors is now available from the Java and Default Text Editors

Source menu on Navigator Views

The Source context menu, which contains Format Document and Convert Line Delimiters actions, has been added to the Navigator View. The actions can be used on a project, a folder, or a document. When the action is used on a project or a folder, the action will be applied to all documents and sub-folders in the project or folder.

In this milestone, the Source actions only supports content types supported by the Source Editor (including XML, HTML, JSP, and CSS). Documents of unsupported content type (for example, bitmaps) will be ignored. In the future, other plug-ins may specify formatters for other content types via an extension point.

Source Menu

The Source action progress dialog is cancellable, in case a large folder is selected by accident, or the action is taking too long. The progress dialog also shows you any exceptions the Source action encountered.

Format Document Progress Dialog
Note: The UI for the Format Document Progress Dialog will change in a future milestone.

In-editor preferences

The source editor context menu now contains a menu item to change preferences relative to the current editor.

In editor preferences menu

This allows users to change editor preferences easily and immediately without having to navigate the entire preferences dialog.

In editor preferences

New Cleanup options

Two new options have been added to Cleanup:

  • Compress empty element tags - compresses empty element tags into the form <tag />
  • Insert required attributes - inserts missing required attributes according to the content model

New QuickAssist proposals

New useful QuickAssist proposals have been added:

  • Surround with new element - surrounds the element at the cursor with a new element. You will enter the linked edit mode after the new element is inserted. You can rename the default start tag name and end tag name at the same time. While in the linked edit mode, Content Assist is available for selecting the element name.
  • Insert required attributes - inserts missing required attributes according to the content model for the element at the cursor
New QuickAssist Proposals

New QuickFix proposals

More smarter QuickFix proposals for common validation errors. For example, when a missing end tag is detected, the following QuickFix proposals are available:

  • Change to empty-element tag - changes this tag into the form <tag />
  • Remove this tag - removes this problem tag
  • Insert end tag before first child element - closes this tag before the first child element
  • Insert end tag at end of element - closes this tag at the end of this element
New QuickFix Proposals

Expand Selection To

The Expand Selection To actions can be used to select elements in the document easily:

  • Enclosing Element - selects the element at the cursor
  • Next Element - expands the selection to the next element
  • Previous Element - expands the selection to the previous element
  • Restore Last Selection - undoes last selection expansion
Expand Selection To Menu

Rename Refactoring

JSP files now participate in the refactoring of Java elements. Renaming a Type, Method, or Package will update the references within JSP files (jsp:useBean tags, import statements, scriptlets, etc.) as well. The necessary changes for JSP files will be computed automatically

Java editor Refactor menu

Refactor results dialog

This can be also invoked directly from the JSP source editor. For example, with a class in a jsp:useBean tag selected, choosing Refactor...Rename from the context menu will launch the familiar Java Refactoring dialog.

Refactor menu in JSP source editor

Move Refactoring

JSP files also participate in the moving of Java source files. After dragging a class MyDate from "one.two.three" into the package "one.two.three.four", when dropped, the user will be prompted to update the affected JSP files.

dialog presented when moving Java sources

This type of refactoring can also be invoked via the editor context menu if a Java element is selected.

Automatic Snippets management by content-type

The Customizer's Show/Hide functionality from earlier releases has been augmented with more fine-grained controls for visibility.

customizer dialog

Users may now select which content-types a drawer applies to. When editing files those content-types, that drawer will be shown. Drawers configured for per-content-type management but not enabled for that content type will be hidden.

content type dialog

Configurable Hover Help

Users can configure the type of hover help displayed, and the keystrokes used to display hover help in Source Editors.

hover help preferences

4.0 Provide Feedback to Us

We encourage development/design feed back on the wtp-dev mailing list. You can subscribe to the list via this link.

For usage questions, discussion of bugs, and strange behaviour please post to the eclipse.webtools newsgroup. Information on the Web Tools Platform newsgroup can be found

Return to the Eclipse Web Tooling Platform Contribution - IBM Getting Started Guide