NetBeans Component Palette 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 opening the Files window (Ctrl-2) and double-clicking the test-jboss-web.xml file that you find there:

   

   The file opens in the Source Editor and the component palette opens, and displays three code snippets, as in the screenshot shown in the introduction of this tutorial. If the component palette does not open automatically, press Ctrl-Shift-8 to open it manually.

5. Choose Tools > Palette Manager from the main menu bar, as shown below:

   

   The Palette Manager appears, containing your new code snippets, as shown below:

   

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.

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 jbosswebxml project node and choose Properties. In the Project Properties dialog box, click Libraries.
2. For each of the following APIs, click "Add...", select the name from the Module list, and then click OK to confirm it:

   

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

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

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://www.netbeans.org/ns/project/1">
    <type>org.netbeans.modules.apisupport.project</type>
    <configuration>
        <data xmlns="http://www.netbeans.org/ns/nb-module-project/2">
            <code-name-base>org.netbeans.modules.jbosswebxml</code-name-base>
            <standalone/>
            <module-dependencies>
                <dependency>
                    <code-name-base>org.netbeans.modules.editor.lib</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <release-version>1</release-version>
                        <specification-version>1.9.0.1</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.netbeans.modules.projectapi</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <release-version>1</release-version>
                        <specification-version>1.9</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.netbeans.spi.palette</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <release-version>0</release-version>
                        <specification-version>1.5</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.dialogs</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>6.4</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.filesystems</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>6.4</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.loaders</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>5.9</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.nodes</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>6.7</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.text</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>6.9</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.util</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>6.8</specification-version>
                    </run-dependency>
                </dependency>
                <dependency>
                    <code-name-base>org.openide.windows</code-name-base>
                    <build-prerequisite/>
                    <compile-dependency/>
                    <run-dependency>
                        <specification-version>6.5</specification-version>
                    </run-dependency>
                </dependency>
            </module-dependencies>
            <public-packages/>
        </data>
    </configuration>
</project>

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 the JBOSSPalette folder, which is defined in the layer.xml file.
PaletteController	Provides access to data in the Component Palette.
PaletteActions	(to be done)

In addition, you will also create the following supporting classes:

File	Description
jbossddPaletteUtilities	Handles insertion and formatting of the dropped code snippet, by implementing two NetBeans API classes: org.netbeans.editor.BaseDocument org.netbeans.editor.Formatter
jbossddPaletteCustomizerAction	Provides the menu item that opens the Palette Manager:
jbossddPaletteDropDefault	(to be done)

To implement the NetBeans Palette API, take the following steps:

1. Right-click the org.netbeans.modules.jbosswebxml project node and choose New > Java Class. Create the first of the following files, type org.netbeans.modules.jbosswebxml.palette in the package drop-down list, click Finish, and then repeat the process to create the others:
   • jbossddPaletteActions
   • jbossddPaletteCustomizerAction
   • jbossddPaletteDropDefault
   • jbossddPaletteFactory
   • jbossddPaletteUtilities

   You should now have the following files (highlighted in the screenshot below):

   

2. Replace the default content of the jbossddPaletteFactory.java file with the following:

   package org.netbeans.modules.jbosswebxml.palette;
   
   import java.io.IOException;
   import org.netbeans.spi.palette.PaletteController;
   import org.netbeans.spi.palette.PaletteFactory;
   
   public class jbossddPaletteFactory {
       
       public static final String JBOSS_PALETTE_FOLDER = "JBOSSPalette";
       
       private static PaletteController palette = null;
       
       public static PaletteController getPalette() throws IOException {
           if (palette == null)
               palette = PaletteFactory.createPalette(JBOSS_PALETTE_FOLDER, new jbossddPaletteActions()); 
           return palette;
       }
   }

3. Replace the default content of the jbossddPaletteActions.java file with the following:

   package org.netbeans.modules.jbosswebxml.palette;
   
   import java.awt.event.ActionEvent;
   import java.io.IOException;
   import javax.swing.AbstractAction;
   import javax.swing.Action;
   import javax.swing.text.JTextComponent;
   import org.netbeans.editor.Utilities;
   import org.netbeans.spi.palette.PaletteActions;
   import org.netbeans.spi.palette.PaletteController;
   import org.openide.DialogDisplayer;
   import org.openide.NotifyDescriptor;
   import org.openide.text.ActiveEditorDrop;
   import org.openide.util.Lookup;
   import org.openide.util.NbBundle;
   
   public class jbossddPaletteActions extends PaletteActions {
       
       /** Creates a new instance of jbossddPaletteActions */
       public jbossddPaletteActions() {
       }
   
       public Action[] getImportActions() {
           return new Action[0]; //TODO implement this
       }
   
       public Action[] getCustomCategoryActions(Lookup category) {
           return new Action[0]; //TODO implement this
       }
   
       public Action[] getCustomItemActions(Lookup item) {
           return new Action[0]; //TODO implement this
       }
   
       public Action[] getCustomPaletteActions() {
           return new Action[0]; //TODO implement this
       }
   
       public Action getPreferredAction( Lookup item ) {
           return new MFPaletteInsertAction(item);
       }
       
       private static class MFPaletteInsertAction extends AbstractAction {
           
           private Lookup item;
           
           MFPaletteInsertAction(Lookup item) {
               this.item = item;
           }
                   
           public void actionPerformed(ActionEvent e) {
         
               ActiveEditorDrop drop = (ActiveEditorDrop) item.lookup(ActiveEditorDrop.class);
               
               JTextComponent target = Utilities.getFocusedComponent();
               if (target == null) {
                   String msg = NbBundle.getMessage(jbossddPaletteActions.class, "MSG_ErrorNoFocusedDocument");
                   DialogDisplayer.getDefault().notify(new NotifyDescriptor.Message(msg, NotifyDescriptor.ERROR_MESSAGE));
                   return;
               }
               
               try {
                   drop.handleTransfer(target);
               }
               finally {
                   Utilities.requestFocus(target);
               }
               
               try {
                   PaletteController pc = jbossddPaletteFactory.getPalette();
                   pc.clearSelection();
               }
               catch (IOException ioe) {
               } //should not occur
   
           }
       }
       
   }

4. Replace the default content of the jbossddPaletteUtilities.java file with the following:

   package org.netbeans.modules.jbosswebxml.palette;
   
   import java.awt.Component;
   import java.awt.Container;
   import java.util.StringTokenizer;
   import javax.swing.JTree;
   import javax.swing.text.BadLocationException;
   import javax.swing.text.Caret;
   import javax.swing.text.Document;
   import javax.swing.text.JTextComponent;
   import org.netbeans.api.project.FileOwnerQuery;
   import org.netbeans.api.project.Project;
   import org.netbeans.api.project.ProjectUtils;
   import org.netbeans.api.project.SourceGroup;
   import org.netbeans.api.project.Sources;
   import org.netbeans.editor.BaseDocument;
   import org.netbeans.editor.Formatter;
   import org.openide.filesystems.FileObject;
   
   public class jbossddPaletteUtilities {
       
       /** Creates a new instance of jbossddPaletteUtilities */
       public jbossddPaletteUtilities() {
       }
       
       public static void insert(String s, JTextComponent target)
       throws BadLocationException {
           insert(s, target, true);
       }
       
       public static void insert(String s, JTextComponent target, boolean reformat)
       throws BadLocationException {
           
           if (s == null)
               s = "";
           
           Document doc = target.getDocument();
           if (doc == null)
               return;
           
           if (doc instanceof BaseDocument)
               ((BaseDocument)doc).atomicLock();
           
           int start = insert(s, target, doc);
           
           if (reformat && start >= 0 && doc instanceof BaseDocument) {  // format the inserted text
               int end = start + s.length();
               Formatter f = ((BaseDocument)doc).getFormatter();
               f.reformat((BaseDocument)doc, start, end);
           }
           
           if (doc instanceof BaseDocument)
               ((BaseDocument)doc).atomicUnlock();
           
       }
       
       private static int insert(String s, JTextComponent target, Document doc)
       throws BadLocationException {
           
           int start = -1;
           try {
               //at first, find selected text range
               Caret caret = target.getCaret();
               int p0 = Math.min(caret.getDot(), caret.getMark());
               int p1 = Math.max(caret.getDot(), caret.getMark());
               doc.remove(p0, p1 - p0);
               
               //replace selected text by the inserted one
               start = caret.getDot();
               doc.insertString(start, s, null);
           } catch (BadLocationException ble) {}
           
           return start;
       }
   }

5. Replace the default content of the jbossddPaletteCustomizerAction.java file with the following:

   package org.netbeans.modules.jbosswebxml.palette;
   
   import java.io.IOException;
   import org.openide.ErrorManager;
   import org.openide.util.HelpCtx;
   import org.openide.util.NbBundle;
   import org.openide.util.actions.CallableSystemAction;
   
   public class jbossddPaletteCustomizerAction extends CallableSystemAction {
   
       private static String name;
       
       public jbossddPaletteCustomizerAction () {
           putValue("noIconInMenu", Boolean.TRUE); // NOI18N
       }
   
       protected boolean asynchronous() {
           return false;
       }
   
       /** Human presentable name of the action. This should be
        * presented as an item in a menu.
        * @return the name of the action
        */
       public String getName() {
           if (name == null)
               name = NbBundle.getBundle(jbossddPaletteCustomizerAction.class).getString("ACT_OpenjbossddCustomizer"); // NOI18N
           
           return name;
       }
   
       /** Help context where to find more about the action.
        * @return the help context for this action
        */
       public HelpCtx getHelpCtx() {
           return null;
       }
   
       /** This method is called by one of the "invokers" as a result of
        * some user's action that should lead to actual "performing" of the action.
        */
       public void performAction() {
           try {
               jbossddPaletteFactory.getPalette().showCustomizer();
           }
           catch (IOException ioe) {
               ErrorManager.getDefault().notify(ErrorManager.EXCEPTION, ioe);
           }
       }
   
   }

6. Replace the default content of the jbossddPaletteDropDefault.java file with the following:

   package org.netbeans.modules.jbosswebxml.palette;
   
   import javax.swing.text.BadLocationException;
   import javax.swing.text.JTextComponent;
   import org.openide.text.ActiveEditorDrop;
   
   public class jbossddPaletteDropDefault implements ActiveEditorDrop {
       
       String body;
   
       public jbossddPaletteDropDefault(String body) {
           this.body = body;
       }
   
       public boolean handleTransfer(JTextComponent targetComponent) {
   
           if (targetComponent == null)
               return false;
   
           try {
               jbossddPaletteUtilities.insert(body, (JTextComponent)targetComponent);
           }
           catch (BadLocationException ble) {
               return false;
           }
           
           return true;
       }
   
   }

7. Right-click the org.netbeans.modules.jbosswebxml.palette node, choose New > File/Folder, and select Properties File from the Other category. Click Next. Name the file Bundle and then click Finish. Add the following keys to the new Bundle.properties file:

   MSG_ErrorNoFocusedDocument=No document selected. Please select a document to insert the item into.
   ACT_OpenJbossddCustomizer=&JBoss Code Clips

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 jbossddPaletteUtilities.java, which defines how the piece of code should be inserted. For example, indentation and formatting are defined here.
• 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.

As an example, when you create three code snippets called ContextRoot.java, ResourceReference.java, and SecurityDomain.java, the result might be as follows (the highlighted packages below contain the code snippets and their supporting resources):

Installing and Using the Module

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

   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.

2. 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 newhtmlsnippet project and choose Create NBM.

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

   

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

3. The recipient can install the module by using the Update Center. Choose Tools > Update Center from the main menu.