modules/ROOT/pages/tutorials/nbm-xmleditor.adoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= NetBeans XML Editor Extension Module Tutorial
:page-layout: platform_tutorial
:jbake-tags: tutorials 
:jbake-status: published
:page-syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:experimental:
:description: NetBeans XML Editor Extension Module Tutorial - Apache NetBeans
:keywords: Apache NetBeans Platform, Platform Tutorials, NetBeans XML Editor Extension Module Tutorial

This tutorial demonstrates how to create a module that extends the functionality offered by one of NetBeans IDE's editors. The IDE has several editors—for example, the XML editor, the Java editor, the JSP editor, and the SQL editor. Normally all the IDE's editors are referred to collectively as the Source Editor. However, each of the editors is distinct—its functionality is targeted at the file type for which it exists.

In this tutorial, you add an action to the XML editor. After you create and install the module, and you open an XML file, the editor's contextual menu will include a menu item that displays the XML file's tags in the Output Window.

// NOTE: This document uses NetBeans Platform 8.0 and above with NetBeans IDE 8.0 and above. If you are using an earlier version of NetBeans IDE or the NetBeans Platform, see  link:74/nbm-xmleditor.html[the previous version of this document].

== Setting up the Module Project

Before you start writing the module, you have to make sure you that your project is set up correctly. The IDE provides a wizard that sets up all the basic files needed for a module.


=== Creating the Module Project


[start=1]
1. Choose File > New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules. Under Projects, select Module. Click Next.

[start=2]
1. In the Name and Location panel, type  ``ShowXMLStructure``  in the Project Name field. Change the Project Location to any directory on your computer. Click Next.

[start=3]
1. In the Basic Module Configuration panel, type  ``org.netbeans.modules.showxmlstructure``  in Code Name Base. 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 the NetBeans APIs. Each is declared as a module dependency.


[start=1]
1. In the Projects window, right-click the Libraries node and choose Add Module Dependency:

[start=2]
1. Search for each of the following APIs in the Add Module Dependency dialog, select the API, and then click OK to confirm it:

*  ``I/O APIs`` 
*  ``Nodes API`` 
*  ``Text API`` 
*  ``Utilities API`` 
*  ``Window System API`` 

In the Projects window, you should see the above included in the list of dependencies.

== Coding the Module

In this section, you use the New Action wizard to create a new Java class, which is annotated such that the user will be able to invoke it after right-clicking within the XML Editor.

[start=1]
1. Right-click the project node and choose New > Other. Under Categories, select Module Development. Under Projects, select Action. Click Next.

[start=2]
1. In the Action Type panel, click Conditionally Enabled. Select  `` link:https://bits.netbeans.org/dev/javadoc/org-openide-text/org/openide/cookies/EditorCookie.html[EditorCookie]`` . Because of this selection, the Action will be enabled when an EditorCookie is available in the Lookup. That will be the case whenever a document is open in the Source Editor. Click Next.

[start=3]
1. 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 Context Menu Item and then select the  ``text/xml``  MIME type.

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.

[start=4]
1. In the Name and Location panel, type  ``ShowXMLStructureActionListener``  as the Class Name and type  ``Show XML Structure``  as the Display Name. Menu items provided by contextual menus do not display icons. Therefore, click Finish and  ``ShowXMLStructureActionListener.java``  is added to the package. The content of the file is as follows:

[source,java]
----

package org.netbeans.modules.showxmlstructure;

import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.awt.ActionRegistration;
import org.openide.cookies.EditorCookie;
import org.openide.util.NbBundle.Messages;

@ActionID(
    category = "Edit",
id = "org.netbeans.modules.showxmlstructure.ShowXMLStructureActionListener")
@ActionRegistration(
    displayName = "#CTL_ShowXMLStructureActionListener")
@ActionReference(path = "Editors/text/xml/Popup", position = 1100)
@Messages("CTL_ShowXMLStructureActionListener=Show XML Structure")
public final class ShowXMLStructureActionListener implements ActionListener {

    private final EditorCookie context;

    public ShowXMLStructureActionListener(EditorCookie context) {
        this.context = context;
    }

    @Override
    public void actionPerformed(ActionEvent ev) {
        // TODO use context
    }
    
}
----


[start=5]
1. In the Source Editor, fill out the  ``actionPerformed``  method as follows, after reading and understanding the comments in the code:

[source,java]
----

@Override
public void actionPerformed(ActionEvent ev) {
    // "XML Structure" tab is created in Output Window for writing the list of tags:
    InputOutput io = IOProvider.getDefault().getIO(Bundle.CTL_ShowXMLStructureActionListener(), false);
    io.select(); //"XML Structure" tab is selected
    try {
        //Get the InputStream from the EditorCookie:
        InputStream is = ((org.openide.text.CloneableEditorSupport) context).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("*").append(attrName).append(" ");
            }
            //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);
    }
}
----


[start=6]
1. You will need these import statements:

[source,java]
----

import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.io.IOException;
import java.io.InputStream;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.awt.ActionRegistration;
import org.openide.cookies.EditorCookie;
import org.openide.util.Exceptions;
import org.openide.util.NbBundle.Messages;
import org.openide.windows.IOProvider;
import org.openide.windows.InputOutput;
import org.openide.xml.XMLUtil;
import org.w3c.dom.Document;
import org.w3c.dom.NamedNodeMap;
import org.w3c.dom.NodeList;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
----


== Building and 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.


[start=1]
1. Open an XML file and right-click anywhere in the Source Editor. Notice the new popup menu item called "Show XML Structure".

[start=2]
1. Choose the menu item and notice that the tag handler prints all the elements and attributes to the Output window (Ctrl-4), which is at at the bottom of the IDE.

xref:front::community/mailing-lists.adoc[Send Us Your Feedback]

== Next Steps

For more information about creating and developing NetBeans modules, see the following resources:

*  xref:kb/docs/platform.adoc[Other Related Tutorials]
*  link:https://bits.netbeans.org/dev/javadoc/[NetBeans API Javadoc]