NetBeans XML Editor Extension Module Tutorial

Creating the Module Project

1. Choose File > New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules. Under Projects, select Module. Click Next.
2. In the Name and Location panel, type ShowXMLStructure in the Project Name field. Change the Project Location to any directory on your computer. Leave the Standalone Module option and Set as Main Project checkbox selected. Click Next.
3. In the Basic Module Configuration panel, type org.netbeans.modules.showxmlstructure in Code Name Base.
4. Select "Generate XML Layer". Leave the locations of both the localizing bundle and the XML layer file so that they will be stored in a package with the name org/netbeans/modules/showxmlstructure. Click Finish.

The IDE creates the ShowXMLStructure 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).

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, as described below.

1. In the Projects window, right-click the ShowXMLStructure 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

   Click OK to exit the Project Properties dialog box.

In the Projects window, expand the Important Files node and double-click Project Metadata and notice that the APIs you selected have been declared as module dependencies.

Creating the Action

1. Right-click the project node and choose New > Other. Under Categories, select Module Development. Under Projects, select Action, as shown below:

   

   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 as the Display Name. You should now see the following:

   

   Menu items provided by contextual menus do not display icons. Therefore, click Finish and ShowXMLStructureAction.java is added to the package. The content of the file is as follows:

   package org.netbeans.modules.showxmlstructure;
   
   import org.openide.cookies.EditorCookie;
   import org.openide.nodes.Node;
   import org.openide.util.HelpCtx;
   import org.openide.util.NbBundle;
   import org.openide.util.actions.CookieAction;
   
   public final class ShowXMLStructureAction extends CookieAction {
   
       protected void performAction(Node[] activatedNodes) {
           EditorCookie editorCookie = activatedNodes[0].getLookup().lookup(EditorCookie.class);
           // TODO use editorCookie
       }
   
       protected int mode() {
           return CookieAction.MODE_EXACTLY_ONE;
       }
   
       public String getName() {
           return NbBundle.getMessage(ShowXMLStructureAction.class, "CTL_ShowXMLStructureAction");
       }
   
       protected Class[] cookieClasses() {
           return new Class[]{EditorCookie.class};
       }
   
       @Override
       protected void initialize() {
           super.initialize();
           // see org.openide.util.actions.SystemAction.iconResource() Javadoc for more details
           putValue("noIconInMenu", Boolean.TRUE);
       }
   
       public HelpCtx getHelpCtx() {
           return HelpCtx.DEFAULT_HELP;
       }
   
       @Override
       protected boolean asynchronous() {
           return false;
       }
   
   }

5. In the Source Editor, rewrite the performAction method as follows, after reading and understanding the comments in the code:

   protected void performAction(Node[] activatedNodes) {
       EditorCookie editorCookie = activatedNodes[0].getLookup().lookup(EditorCookie.class);
       //Get the tab name from the Bundle.properties file:
       String tabName = NbBundle.getMessage(ShowXMLStructureAction.class, "LBL_tabName");
       // "XML Structure" tab is created in Output Window for writing the list of tags:
       InputOutput io = IOProvider.getDefault().getIO(tabName, false);
       io.select(); //"XML Structure" tab is selected
       try {
           //Get the InputStream from the EditorCookie:
           InputStream is = ((org.openide.text.CloneableEditorSupport) editorCookie).getInputStream();
           //Use the NetBeans org.openide.xml.XMLUtil class to create a org.w3c.dom.Document:
           Document doc = XMLUtil.parse(new InputSource(is), true, true, null, null);
           //Create a list of nodes, for all the elements:
           NodeList list = doc.getElementsByTagName("*");
           //Iterate through the list:
           for (int i = 0; i < list.getLength(); i++) {
               //For each node in the list, create a org.w3c.dom.Node:
               org.w3c.dom.Node mainNode = list.item(i);
               //Create a map for all the attributes of the org.w3c.dom.Node:
               NamedNodeMap map = mainNode.getAttributes();
               //Get the name of the node:
               String nodeName = mainNode.getNodeName();
               //Create a StringBuilder for the Attributes of the Node:
               StringBuilder attrBuilder = new StringBuilder();
               //Iterate through the map of attributes:
               for (int j = 0; j < map.getLength(); j++) {
                   //Each iteration, create a new Node:
                   org.w3c.dom.Node attrNode = map.item(j);
                   //Get the name of the current Attribute:
                   String attrName = attrNode.getNodeName();
                   //Add the current Attribute to the StringBuilder:
                   attrBuilder.append("*" + attrName + " ");
               }
               //Print the element and its attributes to the Output window:
               io.getOut().println("ELEMENT: " + nodeName +
                       " --> ATTRIBUTES: " + attrBuilder.toString());
           }
           //Close the InputStream:
           is.close();
       } catch (SAXException ex) {
           Exceptions.printStackTrace(ex);
       } catch (IOException ex) {
           Exceptions.printStackTrace(ex);
       }
   }

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

   LBL_tabName=XML Structure

Installing the Module

In the Projects window, right-click the ShowXMLStructure project and choose Run.

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". Choose the menu item and notice that the tag handler prints all the elements and attributes to the Output window, which is at at the bottom of the IDE, as shown below:

   

4. 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. That is because the New Action wizard created the following entries for you, which cause the action to be available for XML files only:

   <folder name="Actions">
       <folder name="Edit">
           <file name="org-netbeans-modules-showxmlstructure-ShowXMLStructureAction.instance"/>
       </folder>
   </folder>
   <folder name="Editors">
       <folder name="text">
           <folder name="xml">
               <folder name="Popup">
                   <file name="org-netbeans-modules-showxmlstructure-ShowXMLStructureAction.shadow">
                       <attr name="originalFile" stringvalue="Actions/Edit/org-netbeans-modules-showxmlstructure-ShowXMLStructureAction.instance"/>
                       <attr name="position" intvalue="1100"/>
                   </file>
               </folder>
           </folder>
       </folder>
   </folder>

Creating a Shareable Module Binary

1. In the Projects window, right-click the ShowXMLStructure 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, the Plugin Portal.