NetBeans Code Snippet 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 Newhtmlsnippets 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.newhtmlsnippets 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/newhtmlsnippets. Click Finish.

The IDE creates the Newhtmlsnippets 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 use several classes that belong to the 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 Newhtmlsnippets project node and choose Properties. In the Project Properties dialog box, click Libraries.

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

   • Common Palette
   • Text API
   • Utilities API

   Click OK to exit the Project Properties dialog box.

3. 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.

Creating the Code Snippet

1. Right-click the org.netbeans.modules.newhtmlsnippets node and choose New > Java Class. Type BR in Class Name, make sure that the org.netbeans.modules.newhtmlsnippets package is selected in the Package drop-down list, and click Finish.
2. Replace the default content of the BR.java file with the following:

   package org.netbeans.modules.newhtmlsnippets;
   
   import javax.swing.text.BadLocationException;
   import javax.swing.text.JTextComponent;
   import org.netbeans.modules.newhtmlsnippets.HTMLPaletteUtilities;
   import org.openide.text.ActiveEditorDrop;
   
   public class BR implements ActiveEditorDrop {
       
       public BR() {
       }
       
       private String createBody() {
           String Br = "<br>";
           return Br;
       }
       
       public boolean handleTransfer(JTextComponent targetComponent) {
           String body = createBody();
           try {
               HTMLPaletteUtilities.insert(body, targetComponent);
           } catch (BadLocationException ble) {
               return false;
           }
           return true;
       }
       
   }

   Right-click in the Source Editor and choose Format (Alt-Shift-F).

A red error message remains because you have not created the HTMLPaletteUtilities class yet, which you will do in the next section.

Defining the Insertion

In this section, you create the HTMLPaletteUtilities class, which defines the place where the snippet will be dropped.

1. Right-click the org.netbeans.modules.newhtmlsnippets node and choose New > Java Class. Type HTMLPaletteUtilities in Class Name, make sure that the org.netbeans.modules.newhtmlsnippets package is selected in the Package drop-down list, and click Finish.
2. Replace the default content of the HTMLPaletteUtilities.java file with the following:

   package org.netbeans.modules.newhtmlsnippets;
   
   import javax.swing.text.BadLocationException;
   import javax.swing.text.Caret;
   import javax.swing.text.Document;
   import javax.swing.text.JTextComponent;
   import javax.swing.text.StyledDocument;
   import org.openide.text.NbDocument;
   
   public class HTMLPaletteUtilities {
     
       public static void insert(final String s,final JTextComponent target) throws BadLocationException {
           
           final StyledDocument doc = (StyledDocument)target.getDocument();
           
           class AtomicChange implements Runnable {
               
               public void run() {
                   Document value = target.getDocument();
                   if (value == null)
                       return;
                   try {
                       insert(s, target, doc);
                   } catch (BadLocationException e) {}
               }
           }
           
           try {
               NbDocument.runAtomicAsUser(doc, new AtomicChange());
           } catch (BadLocationException ex) {}
           
       }
       
       private static int insert(String s, JTextComponent target, Document doc) throws BadLocationException {
           
           int start = -1;
           
           try {
               
               //firstly, 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);
               
               //then, replace selected text range with the inserted one:
               start = caret.getDot();
               doc.insertString(start, s, null);
           
           } catch (BadLocationException ble) {}
           
           return start;
   
       }
   
   }

   Right-click in the Source Editor and choose Format (Alt-Shift-F).

Declaring the Code Snippet

The NetBeans Editor Palette Item DTD is used to declare the ActiveEditorDrop class, the icons, the display name, and the tooltip.

1. Right-click the org.netbeans.modules.newhtmlsnippets package node and choose New > Other. Select XML Document in the XML folder and click Next. Type BR in File Name. Type \resources at the end of src\org\netbeans\modules\newhtmlsnippets in Folder. Click Finish.
2. Replace the default content of the BR.xml file with the following:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE editor_palette_item PUBLIC "-//NetBeans//Editor Palette Item 1.0//EN"
     "http://www.netbeans.org/dtds/editor-palette-item-1_0.dtd">
   
   <editor_palette_item version="1.0">
   
       <class name="org.netbeans.modules.newhtmlsnippets.BR" />
   
       <icon16 urlvalue="org/netbeans/modules/newhtmlsnippets/resources/BR16.png" />
       <icon32 urlvalue="org/netbeans/modules/newhtmlsnippets/resources/BR32.png" />
      
       <description localizing-bundle="org.netbeans.modules.newhtmlsnippets.Bundle"
                  display-name-key="NAME_html-BR"
                  tooltip-key="HINT_html-BR" />
                  
   </editor_palette_item>

   In the 1.1 DTD, you can define the display name and tooltip without using a properties file. Below, only the difference with the previous XML file definition is highlighted:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE editor_palette_item PUBLIC "-//NetBeans//Editor Palette Item 1.1//EN"
     "http://www.netbeans.org/dtds/editor-palette-item-1_1.dtd">
   
   <editor_palette_item version="1.0">
   
       <class name="org.netbeans.modules.newhtmlsnippets.BR" />
   
       <icon16 urlvalue="org/netbeans/modules/newhtmlsnippets/resources/BR16.png" />
       <icon32 urlvalue="org/netbeans/modules/newhtmlsnippets/resources/BR32.png" />
      
       <inline-description>
          <display-name>New Line</display-name>
          <tooltip>
              <b>
                 br
              </b>
          </tooltip>
       </inline-description>
                  
   </editor_palette_item>

   Note: You can choose either of the two approaches above, depending on your requirements.

3. Add a 16x16 pixel icon and a 32x32 pixel icon to the new resources folder. Name them BR16.png and BR32.png. They can also be in other icon formats, such as GIF or JPG. Make sure that the resource is correctly declared in the BR.xml file. You can right-click them here and then save them to your module's source structure:

   

4. If you want to use a properties file for declaring the palette item's display name and tooltip, which implies that you are using the 1.0 DTD, add the following to the Bundle.properties file:

   

At this point, the project source structure should be as follows:

Registering the Code Snippet

The layer.xml file registers the user interface elements of your module in your application, which in this case is the IDE. Here, we need to register the palette item in the layer.xml file so that the item will appear in the HTML Palette.

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

   <folder name="HTMLPalette">
      <folder name="HTML">
         <file name="BR.xml" url="resources/BR.xml">
            <attr name="position" intvalue="150"/>
         </file>
      </folder>
   </folder>

2. Optionally, you can reorder the items in the palette. When you do so, you can use the user interface provided for this purpose to do so.

   Expand the layer.xml node and then expand <this layer in context>. A folder appears for every folder declared by every layer.xml file of every module registered in the IDE.

   Notice that the "HTMLPalette" folder is marked in bold. This matches the name of the folder you created in your own layer.xml file. Expand the folder and notice that its subfolder, HTML, is also in bold. Expand the HTML folder and notice that the BR.xml resource declaration file that you declared has been added to the resource declaration files provided by other modules:

   

   When you right-click on the node, several options are available, such as "Delete" and "Copy".

   As an experiment, drag the "New Line" node and drop it right below the "Table" node. Double-click the layer.xml file and notice that the value of the "position" element changes whenever you move the "New Line" node to a different place.

Optional: Adding a Customizer

Optionally, you can let a JPanel appear when the palette item is dropped. In the JPanel, you can let the user define values for attributes that relate to the tag that is about to be created. However, note that adding such a customizer is optional. In the case of a line break, which is what we are creating in this tutorial, there are no attributes that relate to the BR tag. For that reason, to illustrate the customizer functionality, we will add a comment before the BR tag, by means of a customizer.

Note: If you check out the html module from the NetBeans sources, you will find many examples of customizers in the org/netbeans/modules/html/palette/items package.

1. Add a dependency on the NetBeans Dialogs API.

2. Use the New File dialog (Ctrl-N) to create a JPanel in the org.netbeans.modules.newhtmlsnippets package. Name it BRCustomizer.

3. Use the Pallette (Ctrl-Shift-8) to drag and drop a JLabel and a JTextField onto the JPanel and arrange the JPanel as follows:

   

4. You will need to declare the following at the top of the BRCustomizer class:

   private Dialog dialog = null;
   private DialogDescriptor descriptor = null;
   private boolean dialogOK = false;
   
   BR br;
   JTextComponent target;

5. Rewrite the BRCustomizer constructor as follows:

   public BRCustomizer(BR br, JTextComponent target) {
       this.br = br;
       this.target = target;
   
       initComponents();
   }

6. In your BRCustomizer class, add this method, so that, in the next steps, you can open the customizer from your ActiveEditorDrop implementation class:

   public boolean showDialog() {
   
       dialogOK = false;
   
       String displayName = "";
       try {
           displayName = NbBundle.getBundle("org.netbeans.modules.newhtmlsnippets.Bundle").getString("NAME_html-BR"); // NOI18N
       } catch (Exception e) {
           //Handle the exception here.
       }
   
       descriptor = new DialogDescriptor(this, NbBundle.getMessage(BRCustomizer.class, "LBL_Customizer_InsertPrefix") + " " + displayName, true,
               DialogDescriptor.OK_CANCEL_OPTION, DialogDescriptor.OK_OPTION,
               new ActionListener() {
   
                   public void actionPerformed(ActionEvent e) {
                       if (descriptor.getValue().equals(DialogDescriptor.OK_OPTION)) {
                           evaluateInput();
                           dialogOK = true;
                       }
                       dialog.dispose();
                   }
   
               });
   
       dialog = DialogDisplayer.getDefault().createDialog(descriptor);
       dialog.setVisible(true);
       repaint();
   
       return dialogOK;
   
   }

7. Define the evaluateInput() method, which is called in the showDialog() method above, as follows:

   private void evaluateInput() {
   
      String comment = jTextField1.getText();
      br.setComment(comment);
   
   }

8. Add to the Bundle.properties file:

   LBL_Customizer_InsertPrefix=Insert
   NAME_html-BR=Line Break

9. Hook your customizer into the ActiveEditorDrop implementation class as follows (only the lines that are changed are highlighted below):

   package org.netbeans.modules.newhtmlsnippets;
   
   import javax.swing.text.BadLocationException;
   import javax.swing.text.JTextComponent;
   import org.netbeans.modules.newhtmlsnippets.HTMLPaletteUtilities;
   import org.openide.text.ActiveEditorDrop;
   
   public class BR implements ActiveEditorDrop {
   
       private String comment = "";
   
       public BR() {
       }
   
       private String createBody() {
           comment = getComment();
           String Br = "<!-- " + comment + " -->"
                   + "\n        <br>";
           return Br;
       }
   
       public boolean handleTransfer(JTextComponent targetComponent) {
   
           BRCustomizer c = new BRCustomizer(this, targetComponent);
           boolean accept = c.showDialog();
           if (accept) {
               String body = createBody();
               try {
                   HTMLPaletteUtilities.insert(body, targetComponent);
               } catch (BadLocationException ble) {
                   accept = false;
               }
           }
           return accept;
   
       }
   
       public String getComment() {
           return comment;
       }
   
       public void setComment(String comment) {
           this.comment = comment;
       }
   
   }

Your project source structure should now include your JPanel:

Trying Out the Code Snippet

Install and try out the code snippet, by following the steps below.

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

2. Create a new HTML file in the IDE. When the HTML file opens, it displays the Component Palette (Ctrl-Shift-8) with one additional code snippet, called "New Line", with a tooltip that displays the result of dragging-and-dropping the item:

   

3. Drag the 'New Line' item into the Source Editor and, if you completed the optional section on creating a customizer (above), you will see a customizer:

   

4. Type a comment, click OK, and notice that a new <br> tag is inserted at the cursor, together with an HTML comment:

   

   Note: Above, the text "breaking up the paragraph with a line break" was typed into the customizer.

Creating a Shareable Module Binary

An NBM file is the binary version of the module that provides the code snippet. Below, using one menu item, we create the NBM file.

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), as shown below:

   

2. Make the module available to others via, for example, the Plugin Portal.
3. The recipient can install the module by using their IDE's Plugin Manager. They would choose Tools > Plugins from the main menu.