NetBeans IDE 5.0 Plug-in Module Quick Start Guide

Feedback

Sample Projects
Just want to play with a sample? In the IDE, choose File > New Project, then expand Samples folder. The IDE includes a feed browser, which is a plug-in module built on top of the NetBeans Platform.

This document takes you through the basics of using NetBeans IDE 5.0 to develop NetBeans plug-in modules. You develop NetBeans plug-in modules for one of two reasons:

  • To extend the NetBeans IDE. You can very easily extend the IDE's functionality with new features. For example, you can write plug-in modules that make your favorite cutting-edge technologies available to the NetBeans IDE. See the NetBeans IDE 5.0 Release Page for information on what the 5.0 release of the IDE has to offer you.

  • To build an application on top of the NetBeans Platform. You can use the core of NetBeans as a platform on top of which you develop rich client applications. You can save a lot of development time by reusing features readily available in the platform. See the NetBeans Platform homepage for more information.

Mainly the first scenario above is covered in this quick start guide, although the principles addressed here also apply to the second. However, note that the NetBeans IDE 5.0 FeedReader Tutorial is a better tutorial for you if you want to learn about developing applications on top of the NetBeans Platform.

This tutorial is designed to get you going as quickly as possible. You will create and install a simple NetBeans plug-in module. The plug-in module will add a new menu item and a toolbar button to the IDE. When you select the menu item or toolbar button, a DialogDisplayer with the text "I'm plugged in!" will be displayed.

The following topics are covered below:

This tutorial can be completed in 20 minutes.

For more information on NetBeans plug-in modules, see the NetBeans Development Project home on the NetBeans website. If you have questions, visit the NetBeans Developer FAQ or use the feedback link at the top of this page.


Setting Up a Plug-in Module Project

Before you start writing the plug-in module, you have to make sure you have all of the necessary software and that your project is set up correctly. NetBeans provides a wizard that sets up all the basic files needed for a plug-in module.

Installing the Software

Before you begin, you need to install the following software on your computer:

Creating a NetBeans Plug-in Module Project

  1. Choose File > New Project. Under Categories, select NetBeans Plug-in Modules.

    NetBeans plug-in module support provides three project types:

    • Module Project. Creates a template for a standalone plug-in module.
    • Library Wrapper Module Project. Creates a plug-in module for an external JAR file required by one or more plug-in modules.
    • Module Suite Project. Creates a template for a set of interdependent plug-in modules and library wrapper modules, which you want to deploy together.

  2. Select Module Project. Click Next.
  3. In the Name and Location panel, type MyFirstModule in Project Name. Change the Project Location to any directory on your computer, such as c:\mymodules. Leave the Standalone Module radio button and the Set as Main Project checkbox selected. Click Next.

  4. In the Basic Module Configuration panel, replace yourorghere in Code Name Base with myorg, so that the whole code name base is org.myorg.myfirstmodule. Notice that the localizing bundle and the XML layer will be stored in the package org.myorg.myfirstmodule. These files do the following:

    • Localizing Bundle. Specifies language-specific strings for internationalization.
    • XML Layer. Registers items such as menus and toolbar buttons in the NetBeans System Filesystem.

    Click Finish. The IDE creates the MyFirstModule 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):

    Initial Projects window.

    In addition to the localizing bundle and the XML layer, the project also includes the following important files:

    • Module Manifest. Declares that the project is a plug-in module. In addition, it sets some module-specific settings, such as the location of the XML layer, the location of the localizing bundle, and the module version.

    • Build Script. Provides a place where you can create your own Ant targets and override those that are specified in nbproject/build-impl.xml.

    • Project Metadata. Contains information such as the project's type, contents, platform, classpath, dependencies, and mappings between project commands and targets in Ant scripts.

    • NetBeans Platform Config. Contains properties used by the IDE or Platform.

    • Per-user NetBeans Platform Config. Contains properties specific to your installation of the IDE. For example, if you are sharing the project over VCS, any properties you set in this file are not checked into the repository. You can copy a property from NetBeans Platform Config into this file and give the property different definitions in each file. The definitions in this file take precedence over those in NetBeans Platform Config.

    You will not need to modify any of these files during this tutorial. Note that the important files listed above are the logical views of the following files in the Files window: manifest.mf, build.xml, nbproject/project.xml, nbproject/platform.properties, and nbproject/private/platform-private.properties, respectively.


Creating a Menu Item and Toolbar Button

You use the NetBeans plug-in module file templates to create the basis of the module's functionality. When you use a file template, the IDE registers the item that you create in the layer.xml file. After using a wizard to create the file template, you use the NetBeans API List to continue developing the module.

Using the Action Wizard

  1. In the Projects window, right-click the project node and choose New > File/Folder. In the New File wizard, choose NetBeans Module Development under Categories and Action under File Types. Click Next.
  2. In the Action Type panel, accept the defaults. Click Next.

  3. In the GUI Registration panel, select Global Menu Item, and select Global Toolbar Button. Set the following values:

    • Category: Tools
    • Menu: Tools
    • Position: Tools - HERE - <separator>
    • Toolbar: Build
    • Position: Run Main Project - HERE - Debug Main Project

    Select Separator Before and Separator After in the Global Menu Item section.

    You should now see the following:

    GUI Registration panel.

    Note the following about the sections in the GUI Registration panel:

    • Category. Specifies where the action will be located in the Keymap section of the Options window.

    • Global Menu Item. Specifies the menu where the action will be registered as a menu item. The position of the menu item within the existing items in the menu can also be set here.

    • Global Toolbar Button. Specifies the toolbar where the action will be registered as a button. The position of the toolbar button within the existing buttons in the toolbar can also be set here.

    • Global Keyboard Shortcut. Specifies a key stroke that will invoke the action.

    • File Type Context Menu Item. Specifies the MIME type of the file type where the menu item will appear. The position of the menu item within the existing menu items and its separators can also be set here. For a detailed scenario that uses this field, see the NetBeans DataLoader Module Tutorial.

    • Editor Context Menu Item. Specifies the MIME type of the editor where the menu item will appear. The position of the menu item within the existing menu items and its separators can also be set here. For a detailed scenario that uses this field, see the NetBeans Editor Extension Module Tutorial.

    Click Next.

  4. In the Name, Icon, and Location panel, type MyFirstAction in Class Name and type My First Action in Display Name. In Icon, browse to a 16x16 pixel icon in your filesystem. For example, you can find some 16x16 pixel icons at the following location within your NetBeans IDE 5.0 installation directory:

       enterprise2\jakarta-tomcat-5.5.9\server\webapps\admin\images

  5. Click Finish.

    The IDE creates MyFirstAction.java in org.myorg.myfirstmodule and opens it in the Source Editor. This is what you should see (click on the links to see the related NetBeans API Javadoc):

       package org.myorg.myfirstmodule;
    
       import org.openide.util.HelpCtx;
       import org.openide.util.actions.CallableSystemAction;
    
       public final class MyFirstAction extends CallableSystemAction {
    
           public void performAction() {
       	// TODO implement action body
           }
    
           public String getName() {
           	return "My First Action";
           }
        
           protected String iconResource() {
            return "org/myorg/myfirstmodule/Groups.gif";
           }
        
           public HelpCtx getHelpCtx() {
            return HelpCtx.DEFAULT_HELP;
           }
    
           protected boolean asynchronous() {
            return false;
           }
       }

    As specified in the GUI Registration panel, the IDE registers the action class as a menu item and as a toolbar button in the layer.xml file:

    <filesystem>
    
        <folder name="Actions">
            <folder name="Tools">
                <file name="org-myorg-myfirstmodule-MyFirstAction.instance">
                    <attr name="instanceClass" stringvalue="org.myorg.myfirstmodule.MyFirstAction"/>
                </file>
            </folder>
        </folder>
    
        <folder name="Menu">
            <folder name="Tools">
                <attr name="org-openide-actions-ToolsAction.instance/org-myorg-myfirstmodule-MyFirstAction.shadow" boolvalue="true"/>
                <file name="org-myorg-myfirstmodule-MyFirstAction.shadow">
                    <attr name="originalFile" stringvalue="Actions/Tools/org-myorg-myfirstmodule-MyFirstAction.instance"/>
                </file>
                <attr name="org-myorg-myfirstmodule-MyFirstAction.shadow/Separator1.instance" boolvalue="true"/>
            </folder>
        </folder>
    
        <folder name="Toolbars">
            <folder name="Build">
                <attr name="org-netbeans-modules-project-ui-RunMainProject.shadow/org-myorg-myfirstmodule-MyFirstAction.shadow" boolvalue="true"/>
                <file name="org-myorg-myfirstmodule-MyFirstAction.shadow">
                    <attr name="originalFile" stringvalue="Actions/Tools/org-myorg-myfirstmodule-MyFirstAction.instance"/>
                </file>
                <attr name="org-myorg-myfirstmodule-MyFirstAction.shadow/org-netbeans-modules-project-ui-DebugMainProject.shadow" boolvalue="true"/>
            </folder>
        </folder>
    
    </filesystem>

  6. In the Source Editor, fill out the performAction() method as follows:

       public void performAction() {
            String msg = "I'm plugged in!";
    	NotifyDescriptor d = new NotifyDescriptor.Message(msg, NotifyDescriptor.INFORMATION_MESSAGE);
    	DialogDisplayer.getDefault().notify(d);      
       }

    The line with the calls to NotifyDescriptor and DialogDisplayer are underlined and marked as an error, similar to the following illustration. This is because the related packages have not been declared yet. You will declare them in the next step.

    Red underline.

  7. In the Projects window, right-click the MyFirstModule project node and choose Properties. In the Libraries pane, click Add. Type notifyd and notice that the returned list narrows until the package that contains NotifyDescriptor is displayed:

    Project properties.

    Click OK. The Dialogs API is added to the Module Dependencies list. Click OK to confirm and exit the Project Properties dialog box.

  8. In the Source Editor, click Alt-Shift-F. Two new import statements are added to the top of the source file and the red underlining disappears. These are the new import statements (click on the links to see the related NetBeans API Javadoc):

       import org.openide.DialogDisplayer;
       import org.openide.NotifyDescriptor;

The plug-in module is now complete. Next, you need to install and use it.

Installing and Using the Plug-in Module

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

Installing the Plug-in Module

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

    The plug-in module is built and installed in the target platform. The target platform is set in Tools > NetBeans Platform Manager. The target platform opens so that you can try out your new plug-in module. The default target IDE or Platform is the installation used by the current instance of the development IDE.

Using the NetBeans Plug-in Module

  1. In the newly opened IDE's menu bar, you should see the new menu and menu item, together with the icon you specified in the Action wizard:

    Invoke my first action.

  2. Choose the menu item to invoke the performAction method in MyFirstAction.java. You should see the JOptionPane with its message:

    JOption Pane.

  3. Click the toolbar button. It calls the same action and so has the same result. It should look something like this:

    Invoke my first action button.

Next Steps

For more advanced tutorials, see the following resources:

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