NetBeans Editor Extension Module Tutorial

Installing the Sample

Take the following steps to install the sample:

1. Unzip the attached file.

2. In the IDE, choose File > Open Project and browse to the folder that contains the unzipped file. Open the module project. It should look as follows:

   

3. Right-click the project node and choose Install/Reload in Target Platform. The target platform opens and the module is installed.

4. Verify that the module is correctly installed by using it as described in the Using the Module section.

Now that you know what the end result looks like, you will create the module from scratch and learn about each part while creating it.

Creating the Module Project

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Plug-in Modules. Under projects, select Module Project and click Next.
2. In the Name and Location panel, type ShowXMLStructure in Project Name. Change the Project Location to any directory on your computer, such as c:\mymodules. Leave the Standalone Module radiobutton selected. Select the Set as Main Project checkbox. Click Next.

3. In the Basic Module Configuration panel, replace yourorghere in Code Name Base with myorg and change ShowXMLStructure to xmltree, so that the whole code name base is org.myorg.xmltree. Add spaces the the default Module Display Name to change it to Show XML Structure. Leave the location of the localizing bundle and XML layer, so that they will be stored in a package with the name org/myorg/xmltree. Click Finish.

The IDE creates the Show XML Structure project. The project contains all of your sources and project metadata, such as the project's Ant build script. The project opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1) and its file structure in the Files window (Ctrl-2). For example, the Projects window should now look as follows:

For basic information on each of the files above, see the Introduction to NetBeans Module Development.

Specifying the Module's Dependencies

You will need to subclass several classes that belong to NetBeans APIs. Each has to be declared as a module dependency. Use the Project Properties dialog box for this purpose.

1. In the Projects window, right-click the System Properties project and choose Properties.

2. For each of the following APIs, click "Add..." in the Libraries panel, select the name from the Module list, and then click OK to confirm it:
   • I/O APIs
   • Nodes API
   • Text API
   • Utilities API
   • Window System API

3. Click OK to exit the Project Properties dialog box.

4. In the Projects window, double-click Project Metadata and note that the APIs you selected have been declared as module dependencies.

Creating the Action

1. Right-click the project node and choose New > File/Folder. Under Categories, select NetBeans Module Development. Under Projects, select Action. Click Next.
2. In the Action Type panel and click Conditionally Enabled. Select EditorCookie, which is the name of the class that lets the Source Editor access the action, as shown below:

   

   Click Next.

3. In the GUI Registration panel, select the 'Edit' category in the Category drop-down list. The Category drop-down list controls where an action is shown in the Keyboard Shortcuts editor in the IDE. Next, select Editor Contect Menu Item and then select the text/xml MIME type, as shown below:

   

   Notice that you can set the position of the menu item and that you can separate the menu item from the item before it and after it. Click Next.

4. In the Name and Location panel, type ShowXMLStructureAction as the Class Name and type Show XML Structure Action as the Display Name. Menu items provided by contextual menus do not display icons. Therefore, click Finish and ShowXMLStructureAction.java is added to the package.

5. In the Source Editor, add the following code to the performAction method:

       public void performAction(Node[] activatedNodes) {
           EditorCookie cookie = (EditorCookie)activatedNodes[0].getCookie(EditorCookie.class); 
           String tabName = NbBundle.getMessage(ShowXMLStructureAction.class,"LBL_tabName");
           
           // "XML Tree" tab is created in output window for writing the list of tags
           InputOutput io = IOProvider.getDefault().getIO(tabName,false);
           io.select(); //XML Tree tab is selected
           OutputWriter writer = io.getOut();
           
           try {
               writer.reset(); //clean the output window
               java.io.InputStream is =  ((org.openide.text.CloneableEditorSupport)cookie).getInputStream();
               parse(new InputSource(is));
               is.close();
               for (int i=0;i<tags.length;i++) {
                   writer.println(tags[i]); //write tag to output window
               }
           } catch (IOException ex) {
           } catch (SAXException ex){
               writer.println("Parse Error: "+ex.getMessage());
           }
           writer.flush();
           writer.close();
       }

6. Add a new method:

        /** Parses XML document and creates the list of tags
        */
       private void parse(InputSource is) throws IOException, SAXException {
           XMLReader xmlReader = XMLUtil.createXMLReader();
           TagHandler handler = new TagHandler();
           xmlReader.setContentHandler(handler);
           xmlReader.parse(is);
           tags = handler.getTags(); 
       }

7. Declare the tags variable at the top of the source file:

       private String[] tags;

8. Press Alt-Shift-F. The IDE automatically adds import statements to the top of the class. Some code is still underlined in red, to indicate that not all of the required packages are on the classpath. Right-click the project node, choose Properties, and click Libraries in the Project Properties dialog box. Click add at the top of the Libraries pane and add the Dialogs API.

   In the ShowXMLStructureAction.java class, press Alt-Shift-F again. The red underlining disappears because the IDE finds the required packages in the Dialogs API.

Localizing the Action

1. Add the display names to the Bundle.properties file:

   ACT_name=Show XML Structure
   LBL_tabName=XML Structure

2. Press Ctrl-S to save the file.

Creating the Tag Handler

1. In the Projects window, expand the project node, expand the Source Packages node, and then right-click the org.myorg.xmltree node. Choose New > File/Folder. Under Categories, choose Java Classes. Under File Types, choose Java Class. Click Next and type TagHandler in Class Name. Click Finish. The new Java class opens in the Source Editor.

2. Replace the default code with the code below:

   package org.myorg.xmltree;
   
   import org.xml.sax.Attributes;
   import org.xml.sax.SAXException;
   
        /** Specific XML handler used for creating list of starting and ending tags, e.g. :
        * <AAA>
        *   <BBB>
        *     <CCC/>
        *   </BBB>
        * </AAA>
        */
   
       public class TagHandler extends org.xml.sax.helpers.DefaultHandler {
          
   	private final int indentLength=2;        
           private java.util.List tagList;
           private String indent;
           private String space;
           private String lastElement;
           
           TagHandler() {
               tagList = new java.util.ArrayList();
               StringBuffer indentBuf = new StringBuffer();
               for (int i=0;i<indentLength;i++) indentBuf.append(' ');
               space=indentBuf.toString();
               indent="";
           }
   
           public void startElement(String uri, String localName, String qName, Attributes attributes) throws SAXException {
               tagList.add(indent+"<"+qName+">");
               indent+=space;
               lastElement=qName;
               
           }
   
           public void endElement(String uri, String localName, String qName) throws SAXException {
               indent=indent.substring(indentLength);
               if (qName.equals(lastElement)) {
                   int lastIndex = tagList.size()-1;
                   String lastInList = (String)tagList.get(lastIndex);
                   String replacedString = lastInList.replace(">","/>");
                   tagList.set(lastIndex,replacedString);
               } else {     
                   tagList.add(indent+"</"+qName+">");
               }
               lastElement=null;
           }
           
           String[] getTags() {
               String[] tags = new String[tagList.size()];
               tagList.toArray(tags);
               return tags;
           }
       }

3. Press Ctrl-S to save the file.

Installing the Module

• In the Projects window, right-click the Show XML Structure project and choose Install/Reload in Target Platform.

  The module is built and installed in the target IDE or Platform. The target IDE or Platform opens so that you can try out your new module. The default target IDE or Platform is the installation used by the current instance of the development IDE. Note that when you run your module, you will be using a temporary test user directory, not the development IDE's user directory.

Using the Module

1. Choose File > New Project (Ctrl-Shift-N) and create a new project.

2. In the Files window (Ctrl-2), expand the project node and then expand the nbproject node. Double-click build-impl.xml so that it opens in the Source Editor.

3. Right-click anywhere in the Source Editor and notice the new popup menu item called "Show XML Structure":

   

4. Choose the menu item and notice that the tag handler prints all the tags to the Output window, which is at at the bottom of the IDE:

   

5. Open a different file type in the Source Editor. For example, open a Java class. Right-click anywhere in the Source Editor and notice that the new popup menu item is not included in the contextual menu.

Creating a Shareable Module Binary

1. In the Projects window, right-click the Show XML Structure project and choose Create NBM.

   The NBM file is created and you can view it in the Files window (Ctrl-2):

   

2. Make it available to others via, for example, e-mail.

Uninstalling the Module

1. Close the IDE or Platform instance that opened when you installed the module.
2. Right-click the project node in the Projects window and choose Clean. Now you no longer have a module installed in the IDE or Platform.