NetBeans Editor Component Palette Module Tutorial

This tutorial needs a review. You can open a JIRA issue, or edit it in GitHub following these contribution guidelines.

This tutorial demonstrates how to create a component palette that provides drag-and-drop code snippets for a new file type. Code snippets serve to speed up coding. The IDE provides a component palette for JSP files, HTML files, and Form files. In this tutorial, you learn how to create a component palette for Java source files.

This document applies to NetBeans IDE 6.7 and above. If you are using an earlier version, see the earlier version of this document.

Optionally, for troubleshooting purposes, you can download the completed sample.

Introduction to Component Palettes

In this tutorial, you implement several classes provided by the NetBeans Palette API. Then you register the new component palette in the layer.xml file, for the text/x-java MIME type. The palette that you create in this way will only be visible if a Java source file is open.

If you do not want to create a new component palette, but only want to add a code snippet to an existing component palette, see the NetBeans Code Snippet Module Tutorial.

Getting to Know the Sample

Take the following steps to install the sample:

  1. Download the completed sample from the Plugin Portal and install it in the IDE.

  1. In the New Project wizard, you will find the sample here:

65 new proj dialog
  1. Complete the wizard and your project source structure will be as follows:

65 new proj wiz
  1. Right-click the project node and choose Run. A new instance of the IDE opens and the module is installed.

  1. Verify that the module is correctly installed by opening a Java source file. You should now see your new Java source file palette, containing one item:

65 open java file
  1. Drag the item into the Java source file and, when you drop the item, you will see the related customizer:

65 customizer in java file
  1. When you complete the customizer, you will have a new main method, together with the comment you typed in the customizer:

65 dropped main method

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.

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.

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

  1. In the Name and Location panel, type JavaSourceFilePalette 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.

  1. In the Basic Module Configuration panel, type org.netbeans.modules.javasourcefilepalette in Code Name Base.

  1. 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/javasourcefilepalette . Click Finish.

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

Creating the Component Palette and Code Snippets

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 JavaSourceFilePalette project node and choose Properties. In the Project Properties dialog box, click Libraries.

  1. For each of the following APIs, click "Add…​", select the name from the Module list, and then click OK to confirm it:

65 proj props 1
  1. Click OK to exit the Project Properties dialog box.

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

Creating the Component Palette

Component Palettes are defined by the NetBeans Palette API. Implementing the NetBeans Palette API for this tutorial means implementing the following NetBeans Palette API classes:

File Description

PaletteFactory

Creates a new instance of the Component Palette. To do so, it invokes the createPalette method which creates a new palette from a specified folder registered in the layer.xml .

PaletteController

Provides access to data in the Component Palette.

PaletteActions

Provides the actions on the palette, categories, and items in the palette.

To use the Palette API to create the palette in this tutorial, take the following steps:

  1. Right-click the JavaSourceFilePalette project node and choose New > Java Class. Create a Java file called JavaSourceFileLayerPaletteFactory .

  1. Replace the default content of the JavaSourceFileLayerPaletteFactory.java file with the following:

public class JavaSourceFileLayerPaletteFactory {

    *//Name of the folder in the layer.xml file that is the root of the palette:*
    public static final String JAVA_PALETTE_FOLDER = "JavaPalette";

    private static PaletteController palette = null;

    public JavaSourceFileLayerPaletteFactory() {
    }

    public static PaletteController createPalette() {
        try {
            if (null == palette)
                palette = PaletteFactory.createPalette(JAVA_PALETTE_FOLDER, new MyActions());
            return palette;
        } catch (IOException ex) {
            Exceptions.printStackTrace(ex);
        }
        return null;
    }

    private static class MyActions extends PaletteActions {

        *//Add new buttons to the Palette Manager here:*
        public Action[] getImportActions() {
            return null;
        }

        *//Add new contextual menu items to the palette here:*
        public Action[] getCustomPaletteActions() {
            return null;
        }

        *//Add new contextual menu items to the categories here:*
        public Action[] getCustomCategoryActions(Lookup arg0) {
            return null;
        }

        *//Add new contextual menu items to the items here:*
        public Action[] getCustomItemActions(Lookup arg0) {
            return null;
        }

        *//Define the default action here:*
        public Action getPreferredAction(Lookup arg0) {
            return null;
        }

    }

}

Adding a DragAndDropHandler

In this section, we change the PaletteController , in the code above, and add a DragAndDropHandler . In doing so, we will let the user drag code snippets FROM the editor INTO the palette:

public static PaletteController createPalette() {
    try {
        if (null == palette) {
            *//Add null for the PaletteFilter, which we are not using here,
            //and then instantiate your implementation of the DragAndDropHandler*:
            palette = PaletteFactory.createPalette(JAVA_PALETTE_FOLDER, new MyActions(), *null, new MyDragAndDropHandler()*);
        }
        return palette;
    } catch (IOException ex) {
        Exceptions.printStackTrace(ex);
    }
    return null;
}

*//Definition of the DragAndDropHandler:
private static class MyDragAndDropHandler extends DragAndDropHandler {

    MyDragAndDropHandler() {
        super(true);
    }

    //Maybe you don't like the default 'add to palette' implementation,
    //so you could create your own here:
    @Override
    public void customize(ExTransferable t, Lookup item) {
    }

}*

The above default implementation is all you need. Now the user will be able to drag from the editor into the palette.

Creating the Code Snippets

Each code snippet requires the following files:

  • A Java class that defines the piece of code to be dragged into the Source Editor. This Java class must refer to JavaSourceFilePaletteUtilities.java , which defines how the piece of code should be inserted. For example, indentation and formatting are defined here.

  • Optionally, a customizer where the user can type something that will be added to the snippet, such as comments.

  • A properties file that defines the labels and tooltips.

  • A 16x16 pixel image for the 'Small Icon' display.

  • A 32x32 pixel image for the 'Big Icon' display.

After you have created or added the above files to the NetBeans module, you declare them in a resource declaration XML file, which you register in the NetBeans System Filesystem by using the layer.xml file.

For details on all of the items above, work through the NetBeans Code Snippet Module Tutorial and refer to the sample that you downloaded at the start of this tutorial.

Registering the Module

In this section, we register the menu item and code snippets in the layer.xml file and in the Bundle.properties file.

  1. Add the following tags to the layer.xml file, between the <filesystem> tags:

<folder name="Editors">
  <folder name="text">
      <folder name="x-java">
          <file name="PaletteFactory.instance">
             <attr name="instanceOf" stringvalue="org.netbeans.spi.palette.PaletteController"/>
             <attr name="instanceCreate" methodvalue="org.netbeans.modules.javasourcefilepalette.JavaSourceFileLayerPaletteFactory.createPalette"/>
          </file>
      </folder>
  </folder>
</folder>

<folder name="JavaPalette">
    <folder name="Items">
        <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.javasourcefilepalette.Bundle"/>
        <file name="Item.xml" url="items/resources/Item.xml">
            <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.javasourcefilepalette.Bundle"/>
        </file>
    </folder>
</folder>
  1. Add the following to the Bundle.properties file that is in the same package as the layer.xml file:

JavaPalette/Items=Items
JavaPalette/Items/Item.xml=Item

The key-value pairs listed above localize the items registered in the layer.xml file.

Building and Installing the Module

The IDE uses an Ant build script to build and install your module. The build script is created for you when you create the module project.

Installing and Using the Module

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

The module is built and installed in the target platform. The target platform opens so that you can try out your new module. The default target platform is the installation used by the current instance of the development IDE.

  1. Verify that the module is correctly installed by using it as shown in Installing the Sample.

Creating a Shareable Module Binary

  1. In the Projects window, right-click the the project node and choose Create NBM.

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

  1. Make the module available to others by uploading it to the Plugin Portal.

  1. The recipient can install the module by using the Plugin Manager. Choose Tools > Plugins from the main menu. Send Us Your Feedback

Next Steps

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