Tools Guide

Chapter 6   Source Editors

Workbench provides two sets of editors, one set based on open-source NetBeans editors and the other set native to Workbench:

• NetBeans-based editors

  • Java Editor

  • JSP Editor

  • HTML Editor

  • XML-related editors

• Native editors

  • Text Editor

  • Text views of the Deployment Descriptor Editor, Deployment Plan Editor, and WSDL Editor

  • Non-default versions of the Java, JSP, and HTML editors

This chapter describes the basic functionality of these editors:

• Common features

• The NetBeans-based editors

• The native editors

Specialized features   Other chapters in this guide cover the specialized features of the following editors:

• Chapter 7, "XML Editors"

• Chapter 8, "WSDL Editor"

• Chapter 10, "Deployment Descriptor Editor"

• Chapter 11, "Deployment Plan Editor"

Common features

This section describes features common to all Workbench editors.

• Standard editing features

• Editor preferences

• Searching across multiple files

• Using text abbreviations

• Changing case

• Changing spaces, tabs, and indentation

Standard editing features

All Workbench editors provide these text-editing features:

Editor preferences

Much of the editor display and behavior can be configured in the Text Editing tab on the Preferences dialog, which you can access using Edit>Preferences. This tab contains settings such as font size displayed in the editors, spaces per tab character, whether to show line numbers, and so on.

    For details, see "Text editing preferences" on page 16.

Searching across multiple files

You can search across multiple files at once. You can search through:

• All files that are open in Workbench

• Files that are in all open projects

• Files in a specified open project

• Specified files on the file system

To search across multiple files:

1. Select Search>Find in Files or press Ctrl+Shift+F.

   The multiple-search Find dialog displays.

   NOTE   You can also access the multiple-search feature from the standard Find dialog in the native editors by clicking the Find in Files button.

2. Specify the following:

   Field	Description
   Search for	The text to search for. You can select previously searched text.
   Search in	The set of files you want to search through
   Direction	Whether to search forward or backward
   Match case	Whether the found text must match the case of the search text
   Match whole word	Whether the found text must be complete words
   Regular expression	Regular expression to search for. For details, see Regular Expressions for Text Searches in the Reference.

3. Click OK.

   Workbench searches through the specified files. All lines of text containing matching text are listed in the Find tab of the Output Pane.

4. To display the found text, double-click the line of text in the Output Pane. You can view each instance of found text in its corresponding source file:

   • Select Search>Next Occurrence (or press F4)

   • Select Search>Previous Occurrence (or press Shift+F4)

Using text abbreviations

You can define abbreviations that can be expanded to one or more lines of text. For example, you can specify that a word can expand to a predefined language construct. For example, the abbreviation main might be defined to expand to this code in a Java file:

  public static void main(String args[])
  {
  
  }

The abbreviations defined in Workbench appear on the Abbreviations tab of the Preferences dialog (Edit>Preferences). From this dialog you can define new abbreviations and change or delete existing abbreviations. For details, see "Abbreviations preferences" on page 19.

Once you have defined an abbreviation, you can replace its name with the associated expanded text using Edit>Text Tools>Complete Abbreviation (or by pressing Ctrl+U).

Changing case

You can easily change the case of text.

Changing spaces, tabs, and indentation

You can change how the native editors use spaces, tabs, and indentation using the menu items under Edit>Text Tools.

The NetBeans-based editors

The core Workbench editors are based on NetBeans, an open-source Java-based framework and set of editors. The core Workbench editors are:

• Java Editor

• JSP Editor

• HTML Editor

• XML-related editors (the XML-related editors have different features than the other NetBeans-based editors and are described in Chapter 7, "XML Editors")

NOTE   Previous releases of Workbench used native versions of the Java, JSP, and HTML editors. The native versions are still provided with Workbench, and you can configure Workbench to use them instead of the NetBeans versions. See Using the native Java, JSP, or HTML editor.

The following sections describe the NetBeans-based editors.

• Color coding

• Code completion

• Adding files types edited by NetBeans-based editors

• Other editing support

Color coding

The NetBeans-based Java, JSP, and HTML editors color-code syntactic elements to make it easy for you to read your code.

The Java Editor uses special colors for these elements:

The HTML Editor uses colors for these elements:

The JSP Editor uses the same colors for Java components as the Java Editor and the same colors for HTML components as the HTML Editor, plus:

Code completion

As you are coding your Java in the Java Editor (or coding Java in a JSP page using the JSP Editor), you can use the Workbench's code completion feature. As you type, you can display a list of possible classes, methods, variables, and so on that can be used to complete the Java expression.

The elements displayed in the Java code completion box are defined by Workbench parser database files. Workbench ships with predefined parser files that include the following classes:

• J2EE 1.2

• JDK 1.3

• Servlet 2.3

• xalan and xerces (the versions that ship with Workbench)

• Ant (the version that ships with Workbench)

• jBroker Web (the version that ships with Workbench)

You can create your own parser database files to make your own classes available for code completion. For details, see Creating parser database files.

To complete a Java expression:

1. In the Java Editor or in a block of Java code in the JSP Editor, type the first few characters of the expression, such as:

     String srcname;
     srcname.
   

2. Press Ctrl+Space or Ctrl+\, or pause after typing a period, a comma, or the keyword new or import (followed by a space).

   The code completion box is displayed, providing a scrolling list of possible classes, methods, variables, and so on that can complete your expression.

   

   In the preceding screen shot, the box lists methods and fields available for strings.

   For methods and fields, the code completion box displays only static or only nonstatic options, depending on the context of your code. The options are color-coded:

   • Classes, methods, and exceptions are red

   • Arguments are magenta

   • Interfaces are gray

   • Fields are blue

3. While the code completion box is displayed, you can do the following:

   Do this	In order to
   Continue to type	Dynamically update the list of items in the code completion box based on your current entry
   Select an item and press Enter	Insert an item into your code and close the code completion box
   Select an item and press Shift+Enter	Insert an item into your code and keep the code completion box open
   Press Tab	Insert into your code the letters that are common to all the items in the list and keep the box open
   Press Escape	Close the box without inserting anything

Inserting methods   If you select a method with arguments, the method is inserted with replacement text for the first argument. If you specify that argument and type a comma, the completion box opens again so you can insert in the next argument, and so on.

Workbench displays the data type of the entered arguments in the title of the code completion box; it displays a question mark if it can't recognize the type. If you enter an argument that does not match any of the recognized argument lists for the method name, all the recognized methods are displayed (along with their argument list), and an asterisk (*) appears for the unrecognized argument(s) in the title of the code completion box.

Creating parser database files

The items displayed in the code completion box are defined by the Workbench parser database files. You can have Workbench create database files of your own classes so that they are listed in the code completion box when appropriate.

To create the parser database files:

1. Open a project.

2. Build the project.

3. Select Edit>Preferences.

4. Select the NetBeans Directories tab.

5. To add your parser files to the same database (directory) as the predefined files, select the directory in the Java Completion Directories box. To put the files in a different database (directory), click Add, specify the directory, and select it.

6. Click Create.

   The Update Parser Databases dialog displays.

7. Specify the following information:

   Setting	Description
   Parser database file prefix	The names of the parser files that will be created. Workbench will create two files: prefix.jcb and prefix.jcs.
   Java source file directory	The root of the directory containing your project's source files, such as c:\myProject\src
   Classes, Methods, and Fields	The visibility of the objects you want to include in the database

8. Click OK to add the files to the parser database.

If you later make changes to your project and want the changes to be reflected in the code completion lists, you must recreate the parser database files.

Adding files types edited by NetBeans-based editors

By default, Workbench is configured to edit .java, .jsp, and .html files with the NetBeans-based editors. You can specify additional file types to edit with these editors. For example, you might have .htm files that you want to edit with the NetBeans-based HTML Editor. You would add .htm as a file type for the HTML Editor.

To edit additional file types with NetBeans-based editors:

1. Select Edit>Preferences.

2. Select the Editor Setup tab.

   This tab lists the NetBeans kits that are installed and allows you to specify which you want to use.

   The list at the bottom of the tab maps file extensions to a NetBeans kit.

3. To add a file type, click Add.

4. Specify the file extension (wild cards are not supported) and the appropriate NetBeans editor kit.

5. Click OK.

   The additional file type is listed in the Extension mappings table. When you open a file with the specified extension, it will open in the associated NetBeans-based editor.

NOTE   You can also specify that you do not want to use a NetBeans-based editor to edit .java, .jsp, or .html files, in which case Workbench will use the corresponding native editor. For details, see Using the native Java, JSP, or HTML editor.

Other editing support

The NetBeans-based editors also provide the following special editing features.

Navigating and selecting text

Deleting text

Searching for text

Changing indentation

Bookmarks

The native editors

The core Workbench editors are based on NetBeans and have the features described above. The following editors are native to Workbench and have a different feature set:

• Text Editor

• Text views of the Deployment Descriptor Editor, Deployment Plan Editor, and WSDL Editor

• Non-default versions of the Java, JSP, and HTML editors

The following sections describe the native editors.

• Changing line ending characters

• Multiple clipboard support

• Viewing and changing read-only and read-write attributes

• Using the native Java, JSP, or HTML editor

• Inserting custom tags in a JSP page

Changing line ending characters

You can convert all DOS-style line ending characters to UNIX-style line ending characters by selecting Edit>Text Tools>Convert to UNIX Line Endings. To convert all UNIX-style line endings to DOS-style endings, select Convert to DOS Line Endings.

NOTE   Changing line endings causes no visual change in the editor.

Multiple clipboard support

You can copy or move multiple instances of text. The editor keeps track of your most recently used clipboards. Copying and cutting multiple times creates a clipboard with multiple listings. When you press Control+Shift+V, the editor lets you select which text to paste.

Viewing and changing read-only and read-write attributes

When you open a file in a native editor, Workbench displays in the bottom-right corner whether the file has read-only (RO) or read-write (RW) permission. If a file is in RO mode, you cannot make changes to it in the editor. You can switch between RO and RW mode by clicking on this indicator.

Switching from RO to RW mode enables you to make changes in the editor. However, the ability to write to the file (for example, using File>Save) is still controlled by the file system permissions for that file. You cannot save changes to a file unless the file is marked writable by the file system.

Using the native Java, JSP, or HTML editor

By default, Workbench uses NetBeans-based Java, JSP, and HTML editors (see The NetBeans-based editors). If you want, you can use the native versions of these editors in order to get the functionality described above for the native editors (plus, with the native JSP Editor, you can use the Custom Tag Wizard; see Inserting custom tags in a JSP page).

To use the native Java, JSP, or HTML editors:

1. Select Edit>Preferences.

2. Select the Editor Setup tab.

   This tab lists the NetBeans kits that are installed and allows you to specify which you want to use.

   The list at the bottom of the tab maps file extensions to a NetBeans kit.

3. If you do not want to use the NetBeans-based editor for a file type (and instead use the native editor), select the file type in the Extension mapping table and click Remove.

4. Click OK to confirm.

File types no longer in the list will use the corresponding native editor, providing the features described for the native editors.

Inserting custom tags in a JSP page

In JSP pages, custom tags enable you to extend the functionality provided by standard JSP tags, either by writing your own tag library or by using a tag library provided by a third party, such as the Jakarta project. Tag libraries consist of the Java classes that provide functionality for the tags and a tag library descriptor file, an XML document that describes the tag library.

You import a tag library into a JSP page using a taglib directive that specifies the location of the tag library descriptor file and declares an identifier that you can use as a prefix to reference the various tags in that library. For example:

  <%@ taglib uri="/WEB-INF/tlds/app.tld" prefix="apptags" %>

references a tag library called app.tld, located in the /WEB-INF/tlds directory in the archive. You can refer to tags in the library using the apptags prefix. For example, if the tag library contains a tag called AskUserName, you could create an instance of that tag in the JSP page using this line:

  <apptags:AskUserName></apptags:AskUserName>

The Custom Tag Wizard

The native Workbench JSP Editor provides a Custom Tag Wizard that enables you to easily insert custom tags into a JSP page.

To insert JSP custom tags using the Custom Tag Wizard:

1. Create the classes and descriptor files for your tag library.

2. Add the classes and descriptor files to your Workbench project. A typical location for class files is a WEB-INF/classes directory; for descriptor files, it is typically WEB-INF/tlds.

3. Edit the JSP file in which you want to use the custom tags, adding a taglib directive to import the tag library.

4. Position the cursor at the point in the JSP file where you want to insert a custom tag.

5. Select Edit>Insert Custom Tag>Custom Tag Wizard.

   NOTE   You must be using the native JSP Editor to access this wizard. See Using the native Java, JSP, or HTML editor).

   If the page has more than one taglib directive, a list of all tag libraries specified on the page displays. For example:

   

   Select the tag library you want to use and click Next.

6. If Workbench cannot find the tag library specified, it prompts you to locate it on your file system.

7. Once you have specified the tag library, a list of all tags contained in that library displays. For example:

   

8. Select the tag you want to insert and click Finish. The custom tag code appears in the JSP file. For example:

   

   In this example, the following lines were added manually in Step 3:

     <%@ taglib uri="SampleTags" prefix="Sample" %>
     <%@ taglib uri="CustomTags" prefix="Custom" %>
   

   The wizard added this line to instantiate the custom tag:

     <Sample:AttributeTag message=""></Sample:AttributeTag>
   

9. If necessary, modify the code inserted by the wizard to complete the tag specification. For example, in the tag in the preceding example you would specify a value for the message attribute.

Tools Guide

Copyright © 2002, SilverStream Software, Inc. All rights reserved.