src/content/platform/tutorials/70/nbm-palette-api2.html - netbeans-website-cleanup - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <!-- -*- xhtml -*- -->
   <title>NetBeans Editor Component Palette Module Tutorial for NetBeans Platform 6.5</title>
   <link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"/>
   <meta name="AUDIENCE" content="NBUSER"/>
   <meta name="TYPE" content="ARTICLE"/>
   <meta name="EXPIRES" content="N"/>
   <meta name="developer" content="gwielenga@netbeans.org"/>
   <meta name="indexed" content="y"/>
   <meta name="description"
  content="A short guide to using the Palette API to create a new palette."/>
 <!--      Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. -->
 <!--     Use is subject to license terms.-->
 </head>
 <body>
 <h1>NetBeans Editor Component Palette Module Tutorial</h1>

 <p>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.</p>

     <p><strong class="notes">Note: </strong>This document applies to NetBeans IDE 6.7 and above. If you
     are using an earlier version, see <a href="68/nbm-palette-api2.html">the earlier version
     of this document</a>.</p>

    <p><b>Contents</b></p>

    <p><img src="../../images/articles/69/netbeans-stamp7-8-9.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 6.5, 6.7, 6.8" title="Content on this page applies to NetBeans IDE 6.5, 6.7, 6.8"/></p>
       <ul class="toc">
 <li><a href="#intro">Introduction to Component Palettes</a>
 <ul>
 <li><a href="#installing-sample">Getting to Know the Sample</a></li>
 </ul>
 </li>

 <li><a href="#creatingthemoduleproject">Setting Up the Module Project</a></li>

 <li><a href="#coding-module">Creating the Component Palette and Code Snippets</a>
 <ul>
 <li><a href="#creating-palettes">Creating the Component Palette</a></li>
 <li><a href="#adding-drag-handler">Adding a DragAndDropHandler</a></li>
 <li><a href="#creating-snippets">Creating the Code Snippets</a></li>
 </ul></li>


 <li><a href="#registering-module">Registering the Module</a>

 <ul>
 <li><a href="#declaring-resources">Declaring the Resources</a></li>
 <li><a href="#registering-resoucres">Registering the Resources</a></li>
 </ul>
 </li>

 <li><a href="#reusing">Reusing Code Snippets from Other Palettes</a></li>


 <li><a href="#building">Building and Installing the Module</a>
 <ul>
 <li><a href="#install-plugin">Installing and Using the Module</a></li>
 <li><a href="#share-plugin">Creating a Shareable Module Binary</a></li>
 </ul></li>

 </ul>


 <p><b>To follow this tutorial, you need the software and resources listed in the following
 table.</b></p>

       <table>
         <tbody>
             <tr>
                 <th class="tblheader" scope="col">Software or Resource</th>
                 <th class="tblheader" scope="col">Version Required</th>
             </tr>
             <tr>
                 <td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td>
                 <td class="tbltd1">version 6.7 or above</td>
             </tr>
             <tr>
                 <td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">Java Developer Kit (JDK)</a></td>
                 <td class="tbltd1">Version 6 or<br/>version 5</td>
             </tr>
         </tbody>
     </table>

   <p class="tips">Optionally, for troubleshooting purposes, you
   can <a href="http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=2761">download the completed sample</a>.</p>

 <h2 class="tutorial"><a name="intro"></a>Introduction to Component Palettes</h2>

  <p>In this tutorial, you implement several classes provided by the
  <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html">NetBeans Palette API</a>.
  Then you register the new component palette in the <tt>layer.xml</tt> file, for the <tt>text/x-java</tt>
   MIME type. The palette that you create in this way will only be visible if a Java source file
   is open.</p>

 <p>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 <a href="nbm-palette-api1.html">NetBeans Code Snippet Module Tutorial</a>.</p>


 <div class="indent">
   <h3 class="tutorial"><a name="installing-sample"></a>Getting to Know the Sample</h3>
 <p>Take the following steps to install the sample:</p>
 <ol><li><a href="http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=2761">Download the completed sample</a>
  from the Plugin Portal and install it in the IDE.</li>
     <li>In the New Project wizard, you will find the sample here:
 <p><img src="../../images/tutorials/componentpalette/65-new-proj-dialog.png" alt="New Project dialog"/></p></li>
     <li>Complete the wizard and your project source structure will be as follows:
 <p><img src="../../images/tutorials/componentpalette/65-new-proj-wiz.png" alt="Projects window initially"/></p></li>
 <li>Right-click the project node and choose Run. A new instance of the IDE opens and the module is installed.</li>
  <li>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:
 <p><img src="../../images/tutorials/componentpalette/65-open-java-file.png" alt="" alt="Open Java source file"/></p></li>
 <li>Drag the item into the Java source file and, when you drop the item, you will see the related customizer:
 <p><img src="../../images/tutorials/componentpalette/65-customizer-in-java-file.png" alt="Customizer"/></p></li>
  <li>When you complete the customizer, you will have a new main method, together with the
   comment you typed in the customizer:
 <p><img src="../../images/tutorials/componentpalette/65-dropped-main-method.png" alt="" alt="Dropped main method"/></p></li>
 </ol>
 <p>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.</p>
   </div>

 <!-- ===================================================================================== -->

 <h2 class="tutorial"><a name="creatingthemoduleproject"></a>Setting up the Module Project</h2>
 <p>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.</p>

 <ol>
     <li>Choose File &gt; New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules.
         Under Projects, select Module. Click Next.</li>
     <li>In the Name and Location panel, type <tt>JavaSourceFilePalette</tt> 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.</li>
     <li>In the Basic Module Configuration panel, type <tt>org.netbeans.modules.javasourcefilepalette</tt>
      in Code Name Base.</li>
     <li>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 <tt>org/netbeans/modules/javasourcefilepalette</tt>. Click Finish.</li>
 </ol>

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

 <!-- ===================================================================================== -->
 <h2><a name="coding-module"></a>Creating the Component Palette and Code Snippets</h2>

 <div class="indent">

 <h3 class="tutorial"><a name="specifying"></a>Specifying the Module's Dependencies</h3>

 <p>You will need to subclass several classes that belong to <a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans APIs</a>.
  Each has to be declared as a Module dependency. Use the Project Properties dialog box for this purpose.</p>

  <ol>
 	  <li>In the Projects window, right-click the <tt>JavaSourceFilePalette</tt> project node and choose Properties.
  In the Project Properties dialog box, click Libraries.</li>

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

 <p><img src="../../images/tutorials/componentpalette/65-proj-props-1.png" alt="Setting dependencies"/></p></li>
 <li>Click OK to exit the Project Properties dialog box.</li>
 <li>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.</li>

   </ol>

 <h3 class="tutorial"><a name="creating-palettes"></a>Creating the Component Palette</h3>

 <p>Component Palettes are defined
  by the <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html">NetBeans Palette API</a>.
  Implementing the NetBeans Palette API for this tutorial means implementing the following NetBeans Palette API classes:</p>

 <table width="76%" border="1">

     <tbody><tr>
       <td>
 	<div align="left"><b>File</b></div>
       </td>
       <td>
 	<div align="left"><b>Description</b></div>

       </td>
     </tr>
     <tr>
       <td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html">PaletteFactory</a></tt></td>
       <td>Creates a new instance of the Component Palette. To do so, it invokes
  the <tt>createPalette</tt> method which creates a new palette from a specified folder
  registered in the <tt>layer.xml</tt>.</td>
     </tr>
 <tr>
       <td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html">PaletteController</a></tt></td>
       <td>Provides access to data in the Component Palette.</td>
     </tr>
     <tr>
 	    <td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html">PaletteActions</a></tt></td>

       <td>Provides the actions on the palette, categories, and items in the palette.


       </td>

     </tr>

     </tbody>
   </table>

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

 <ol>

 	<li>Right-click the <tt>JavaSourceFilePalette</tt> project node and
 	      choose New &gt; Java Class. Create a Java file called <tt>JavaSourceFileLayerPaletteFactory</tt>.</li>

  <li>Replace the default content of the <tt>JavaSourceFileLayerPaletteFactory.java</tt> file with the following:

 <pre class="examplecode">public class JavaSourceFileLayerPaletteFactory {

     <b>//Name of the folder in the layer.xml file that is the root of the palette:</b>
     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 {

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

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

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

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

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

     }

 }</pre></li>

 </ol>

 <h3 class="tutorial"><a name="adding-drag-handler"></a>Adding a DragAndDropHandler</h3>

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

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

 <b>//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) {
     }

 }</b></pre>

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

 <h3 class="tutorial"><a name="creating-snippets"></a>Creating the Code Snippets</h3>

 <p>Each code snippet requires the following files:</p>

 <ul>
 <li>A Java class that defines the piece of code to be dragged into the Source Editor. This Java class
  must refer to <tt>JavaSourceFilePaletteUtilities.java</tt>, which defines how the piece of code should be
  inserted. For example, indentation and formatting are defined here.</li>
  <li>Optionally, a customizer where the user can type something that will be added to
   the snippet, such as comments.</li>
 <li>A properties file that defines the labels and tooltips.</li>
 <li>A 16x16 pixel image for the 'Small Icon' display.</li>
 <li>A 32x32 pixel image for the 'Big Icon' display.</li></ul>

 <p>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 <tt>layer.xml</tt> file.</p>

 <p>For details on all of the items above, work through the
  <a href="nbm-palette-api1.html">NetBeans Code Snippet Module Tutorial</a> and refer to
  the sample that you downloaded at the start of this tutorial.</p>

  </div>

 <h2><a name="registering-module"></a>Registering the Module</h2>

 <p>In this section, we register the menu item
 and code snippets in the <tt>layer.xml</tt> file and in the
 <tt>Bundle.properties</tt> file.</p>

 <ol>

     <li>Add the following tags to the <tt>layer.xml</tt> file, between the &lt;filesystem&gt; tags:

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

 &lt;folder name="JavaPalette"&gt;
     &lt;folder name="Items"&gt;
         &lt;attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.javasourcefilepalette.Bundle"/&gt;
         &lt;file name="Item.xml" url="items/resources/Item.xml"&gt;
             &lt;attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.javasourcefilepalette.Bundle"/&gt;
         &lt;/file&gt;
     &lt;/folder&gt;
 &lt;/folder&gt;
 </pre></li>

     <li>Add the following to the <tt>Bundle.properties</tt> file that is in the same package as
     the <tt>layer.xml</tt> file:

 <pre class="examplecode">JavaPalette/Items=Items
 JavaPalette/Items/Item.xml=Item
 </pre>

     <p>The key-value pairs listed above localize the items registered in the <tt>layer.xml</tt> file.</p></li>

 </ol>

 <!-- ======================================================================================= -->

 <h2><a name="building"></a>Building and Installing the Module</h2>
 <p>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.</p>
 <div class="indent">

 	<h3 class="tutorial"><a name="install-plugin"></a>Installing and Using the Module</h3>

       <ol>
 	      <li><p>In the Projects window, right-click the <tt>JavaSourceFilePalette</tt> project and choose Run.</p>
 	      <p>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.</p></li>
                       <li>Verify that the module is correctly installed by using it as
                       shown in <a href="#installing-sample">Installing the Sample</a>.</li>
                   </ol>

                   <h3 class="tutorial"><a name="share-plugin"></a>Creating a Shareable Module Binary</h3>

                   <ol>
               <li><p>In the Projects window, right-click the the project node and choose Create NBM.</p>

 	      <p>The NBM file is created and you can view it in the Files window (Ctrl-2).</p></li>
 	      <li><p>Make the module available to others by uploading it to the <a href="http://plugins.netbeans.org">Plugin Portal</a>.</p></li>
 	      <li>The recipient can install the module by using the Plugin Manager. Choose Tools &gt; Plugins
 	       from the main menu.</li>
        </ol>
 </div>

 <div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&amp;subject=Feedback:%20Component%20Palette%20Module%20Tutorial">Send Us Your Feedback</a></div>
 <!-- ======================================================================================== -->

 <h2><a name="nextsteps"></a>Next Steps</h2>

 <p>For more information about creating and developing NetBeans modules, see the following resources: </p>
   <ul>
 	  <li><a href="https://netbeans.org/kb/trails/platform.html">Other Related Tutorials</a></li>
 	  <li><a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans API Javadoc</a></li>
   </ul>

 <!-- ========================================================================================

 <h2><a name="version"></a>Versioning </h2>

 <table width="76%" border="1">
  <tbody>
    <tr>
       <td>
         <div align="left"><b>Version</b></div>
       </td>
       <td>
 	<div align="left"><b>Date</b></div>
       </td>
       <td>
 	<div align="left"><b>Changes</b></div>
 </td>
 <td>
 	<div align="left"><b>Open Issues</b></div>
       </td>
   </tr>
   <tr>
       <td>
          1
       </td>
       <td>
 	      29 November 2005
       </td>
       <td>
          Initial version
  </td>
 <td>
 	<ul>
 		<li>Needs to be reviewed! Use at your own risk!
 		<li>Need to add explanation for adding own dialog box for predefining values.
 		<li>Explanatory text for the use of the NetBeans APIs to be added.
 		<li>Check for copy-paste errors.
 		<li>Need to add more Javadoc links, for NetBeans API classes in the code.


 	</ul>
       </td>
   </tr>

  <tr>
       <td>
          2
       </td>
       <td>
 	      30 November 2005
       </td>
       <td>
 	      <li>Changed the ZIP file because of problems (see <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=69571">Issue 69571</a>).
 	      <li>Removed hyphens and changed screenshots.
  </td>
 <td>
 	All other issues from above must still be done.
       </td>
   </tr>
 <tr>
       <td>
          3
       </td>
       <td>
 	      8 December 2005
       </td>
       <td>
 	      <li>Fixed reopened issue <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=69571">Issue 69571</a>
 <td>
 	All other issues from above must still be done.
       </td>
   </tr>
   <tr>
       <td>
          4
       </td>
       <td>
 	      22 August 2006
       </td>
       <td>
 	      <li>Minor tweaks.
 <td>
 	All other issues from above must still be done.
         <br>Discovered that the editor support file is missing in the tutorial,
          but not in the module that you can download from the top of the file.
         <br>Discovered that there are several gaps and tbds in this tutorial.
       </td>
   </tr>
    <tr>
       <td>
          5
       </td>
       <td>
 	      30 May 2007
       </td>
       <td>
 	Began updating this tutorial for 6.0.
       </td>
       <td>
           ...
       </td>
   </tr>
    <tr>
       <td>
          6
       </td>
       <td>
 	      5 November 2008
       </td>
       <td>
 	Began & completed updating this tutorial for 6.5.
     <p>Main changes:
     <ul>
         <li>New sample download link to Plugin Portal.
         <li>Rewritten code to use <tt>layer.xml</tt> registration.
         <li>Instead of JBoss palette and snippets for JBoss XML file,
         created a palette for Java source files, which is now
         possible because editor and palette do not need to be
         in the same module. Therefore sections like
         'Recognizing the New File Type' are not necessary (except
         if the palette is for a new file type, in which case
         the File Type Module tutorial should first be used).
         <li>Omitted the code for creating the palette item, because
         it is already described in the Code Snippet Module Tutorial.
     </ul>
       </td>
       <td>
 	      3 August 2009
       </td>
       <td>
 Fixed broken element tags so that formatting is now correct.
       </td>
   </tr>
   </tbody>
 </table>-->
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<!-- -- xhtml -- -->
	<title>NetBeans Editor Component Palette Module Tutorial for NetBeans Platform 6.5</title>
	<link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"/>
	<meta name="AUDIENCE" content="NBUSER"/>
	<meta name="TYPE" content="ARTICLE"/>
	<meta name="EXPIRES" content="N"/>
	<meta name="developer" content="gwielenga@netbeans.org"/>
	<meta name="indexed" content="y"/>
	<meta name="description"
	content="A short guide to using the Palette API to create a new palette."/>
	<!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. -->
	<!-- Use is subject to license terms.-->
	</head>
	<body>
	<h1>NetBeans Editor Component Palette Module Tutorial</h1>

	<p>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.</p>

	<p><strong class="notes">Note: </strong>This document applies to NetBeans IDE 6.7 and above. If you
	are using an earlier version, see <a href="68/nbm-palette-api2.html">the earlier version
	of this document</a>.</p>

	<p><b>Contents</b></p>

	<p><img src="../../images/articles/69/netbeans-stamp7-8-9.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 6.5, 6.7, 6.8" title="Content on this page applies to NetBeans IDE 6.5, 6.7, 6.8"/></p>
	<ul class="toc">
	<li><a href="#intro">Introduction to Component Palettes</a>
	<ul>
	<li><a href="#installing-sample">Getting to Know the Sample</a></li>
	</ul>
	</li>

	<li><a href="#creatingthemoduleproject">Setting Up the Module Project</a></li>

	<li><a href="#coding-module">Creating the Component Palette and Code Snippets</a>
	<ul>
	<li><a href="#creating-palettes">Creating the Component Palette</a></li>
	<li><a href="#adding-drag-handler">Adding a DragAndDropHandler</a></li>
	<li><a href="#creating-snippets">Creating the Code Snippets</a></li>
	</ul></li>


	<li><a href="#registering-module">Registering the Module</a>

	<ul>
	<li><a href="#declaring-resources">Declaring the Resources</a></li>
	<li><a href="#registering-resoucres">Registering the Resources</a></li>
	</ul>
	</li>

	<li><a href="#reusing">Reusing Code Snippets from Other Palettes</a></li>


	<li><a href="#building">Building and Installing the Module</a>
	<ul>
	<li><a href="#install-plugin">Installing and Using the Module</a></li>
	<li><a href="#share-plugin">Creating a Shareable Module Binary</a></li>
	</ul></li>

	</ul>


	<p><b>To follow this tutorial, you need the software and resources listed in the following
	table.</b></p>

	<table>
	<tbody>
	<tr>
	<th class="tblheader" scope="col">Software or Resource</th>
	<th class="tblheader" scope="col">Version Required</th>
	</tr>
	<tr>
	<td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td>
	<td class="tbltd1">version 6.7 or above</td>
	</tr>
	<tr>
	<td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">Java Developer Kit (JDK)</a></td>
	<td class="tbltd1">Version 6 or<br/>version 5</td>
	</tr>
	</tbody>
	</table>

	<p class="tips">Optionally, for troubleshooting purposes, you
	can <a href="http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=2761">download the completed sample</a>.</p>

	<h2 class="tutorial"><a name="intro"></a>Introduction to Component Palettes</h2>

	<p>In this tutorial, you implement several classes provided by the
	<a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html">NetBeans Palette API</a>.
	Then you register the new component palette in the <tt>layer.xml</tt> file, for the <tt>text/x-java</tt>
	MIME type. The palette that you create in this way will only be visible if a Java source file
	is open.</p>

	<p>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 <a href="nbm-palette-api1.html">NetBeans Code Snippet Module Tutorial</a>.</p>


	<div class="indent">
	<h3 class="tutorial"><a name="installing-sample"></a>Getting to Know the Sample</h3>
	<p>Take the following steps to install the sample:</p>
	<ol><li><a href="http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=2761">Download the completed sample</a>
	from the Plugin Portal and install it in the IDE.</li>
	<li>In the New Project wizard, you will find the sample here:
	<p><img src="../../images/tutorials/componentpalette/65-new-proj-dialog.png" alt="New Project dialog"/></p></li>
	<li>Complete the wizard and your project source structure will be as follows:
	<p><img src="../../images/tutorials/componentpalette/65-new-proj-wiz.png" alt="Projects window initially"/></p></li>
	<li>Right-click the project node and choose Run. A new instance of the IDE opens and the module is installed.</li>
	<li>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:
	<p><img src="../../images/tutorials/componentpalette/65-open-java-file.png" alt="" alt="Open Java source file"/></p></li>
	<li>Drag the item into the Java source file and, when you drop the item, you will see the related customizer:
	<p><img src="../../images/tutorials/componentpalette/65-customizer-in-java-file.png" alt="Customizer"/></p></li>
	<li>When you complete the customizer, you will have a new main method, together with the
	comment you typed in the customizer:
	<p><img src="../../images/tutorials/componentpalette/65-dropped-main-method.png" alt="" alt="Dropped main method"/></p></li>
	</ol>
	<p>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.</p>
	</div>

	<!-- ===================================================================================== -->

	<h2 class="tutorial"><a name="creatingthemoduleproject"></a>Setting up the Module Project</h2>
	<p>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.</p>

	<ol>
	<li>Choose File > New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules.
	Under Projects, select Module. Click Next.</li>
	<li>In the Name and Location panel, type <tt>JavaSourceFilePalette</tt> 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.</li>
	<li>In the Basic Module Configuration panel, type <tt>org.netbeans.modules.javasourcefilepalette</tt>
	in Code Name Base.</li>
	<li>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 <tt>org/netbeans/modules/javasourcefilepalette</tt>. Click Finish.</li>
	</ol>

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

	<!-- ===================================================================================== -->
	<h2><a name="coding-module"></a>Creating the Component Palette and Code Snippets</h2>

	<div class="indent">

	<h3 class="tutorial"><a name="specifying"></a>Specifying the Module's Dependencies</h3>

	<p>You will need to subclass several classes that belong to <a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans APIs</a>.
	Each has to be declared as a Module dependency. Use the Project Properties dialog box for this purpose.</p>

	<ol>
	<li>In the Projects window, right-click the <tt>JavaSourceFilePalette</tt> project node and choose Properties.
	In the Project Properties dialog box, click Libraries.</li>

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

	<p><img src="../../images/tutorials/componentpalette/65-proj-props-1.png" alt="Setting dependencies"/></p></li>
	<li>Click OK to exit the Project Properties dialog box.</li>
	<li>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.</li>

	</ol>

	<h3 class="tutorial"><a name="creating-palettes"></a>Creating the Component Palette</h3>

	<p>Component Palettes are defined
	by the <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html">NetBeans Palette API</a>.
	Implementing the NetBeans Palette API for this tutorial means implementing the following NetBeans Palette API classes:</p>

	<table width="76%" border="1">

	<tbody><tr>
	<td>
	<div align="left"><b>File</b></div>
	</td>
	<td>
	<div align="left"><b>Description</b></div>

	</td>
	</tr>
	<tr>
	<td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html">PaletteFactory</a></tt></td>
	<td>Creates a new instance of the Component Palette. To do so, it invokes
	the <tt>createPalette</tt> method which creates a new palette from a specified folder
	registered in the <tt>layer.xml</tt>.</td>
	</tr>
	<tr>
	<td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html">PaletteController</a></tt></td>
	<td>Provides access to data in the Component Palette.</td>
	</tr>
	<tr>
	<td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html">PaletteActions</a></tt></td>

	<td>Provides the actions on the palette, categories, and items in the palette.


	</td>

	</tr>

	</tbody>
	</table>

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

	<ol>

	<li>Right-click the <tt>JavaSourceFilePalette</tt> project node and
	choose New > Java Class. Create a Java file called <tt>JavaSourceFileLayerPaletteFactory</tt>.</li>

	<li>Replace the default content of the <tt>JavaSourceFileLayerPaletteFactory.java</tt> file with the following:

	<pre class="examplecode">public class JavaSourceFileLayerPaletteFactory {

	<b>//Name of the folder in the layer.xml file that is the root of the palette:</b>
	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 {

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

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

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

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

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

	}

	}</pre></li>

	</ol>

	<h3 class="tutorial"><a name="adding-drag-handler"></a>Adding a DragAndDropHandler</h3>

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

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

	<b>//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) {
	}

	}</b></pre>

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

	<h3 class="tutorial"><a name="creating-snippets"></a>Creating the Code Snippets</h3>

	<p>Each code snippet requires the following files:</p>

	<ul>
	<li>A Java class that defines the piece of code to be dragged into the Source Editor. This Java class
	must refer to <tt>JavaSourceFilePaletteUtilities.java</tt>, which defines how the piece of code should be
	inserted. For example, indentation and formatting are defined here.</li>
	<li>Optionally, a customizer where the user can type something that will be added to
	the snippet, such as comments.</li>
	<li>A properties file that defines the labels and tooltips.</li>
	<li>A 16x16 pixel image for the 'Small Icon' display.</li>
	<li>A 32x32 pixel image for the 'Big Icon' display.</li></ul>

	<p>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 <tt>layer.xml</tt> file.</p>

	<p>For details on all of the items above, work through the
	<a href="nbm-palette-api1.html">NetBeans Code Snippet Module Tutorial</a> and refer to
	the sample that you downloaded at the start of this tutorial.</p>

	</div>

	<h2><a name="registering-module"></a>Registering the Module</h2>

	<p>In this section, we register the menu item
	and code snippets in the <tt>layer.xml</tt> file and in the
	<tt>Bundle.properties</tt> file.</p>

	<ol>

	<li>Add the following tags to the <tt>layer.xml</tt> file, between the <filesystem> tags:

	<pre class="examplecode"><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>
	</pre></li>

	<li>Add the following to the <tt>Bundle.properties</tt> file that is in the same package as
	the <tt>layer.xml</tt> file:

	<pre class="examplecode">JavaPalette/Items=Items
	JavaPalette/Items/Item.xml=Item
	</pre>

	<p>The key-value pairs listed above localize the items registered in the <tt>layer.xml</tt> file.</p></li>

	</ol>

	<!-- ======================================================================================= -->

	<h2><a name="building"></a>Building and Installing the Module</h2>
	<p>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.</p>
	<div class="indent">

	<h3 class="tutorial"><a name="install-plugin"></a>Installing and Using the Module</h3>

	<ol>
	<li><p>In the Projects window, right-click the <tt>JavaSourceFilePalette</tt> project and choose Run.</p>
	<p>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.</p></li>
	<li>Verify that the module is correctly installed by using it as
	shown in <a href="#installing-sample">Installing the Sample</a>.</li>
	</ol>

	<h3 class="tutorial"><a name="share-plugin"></a>Creating a Shareable Module Binary</h3>

	<ol>
	<li><p>In the Projects window, right-click the the project node and choose Create NBM.</p>

	<p>The NBM file is created and you can view it in the Files window (Ctrl-2).</p></li>
	<li><p>Make the module available to others by uploading it to the <a href="http://plugins.netbeans.org">Plugin Portal</a>.</p></li>
	<li>The recipient can install the module by using the Plugin Manager. Choose Tools > Plugins
	from the main menu.</li>
	</ol>
	</div>

	<div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20Component%20Palette%20Module%20Tutorial">Send Us Your Feedback</a></div>
	<!-- ======================================================================================== -->

	<h2><a name="nextsteps"></a>Next Steps</h2>

	<p>For more information about creating and developing NetBeans modules, see the following resources: </p>
	<ul>
	<li><a href="https://netbeans.org/kb/trails/platform.html">Other Related Tutorials</a></li>
	<li><a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans API Javadoc</a></li>
	</ul>

	<!-- ========================================================================================

	<h2><a name="version"></a>Versioning </h2>

	<table width="76%" border="1">
	<tbody>
	<tr>
	<td>
	<div align="left"><b>Version</b></div>
	</td>
	<td>
	<div align="left"><b>Date</b></div>
	</td>
	<td>
	<div align="left"><b>Changes</b></div>
	</td>
	<td>
	<div align="left"><b>Open Issues</b></div>
	</td>
	</tr>
	<tr>
	<td>
	1
	</td>
	<td>
	29 November 2005
	</td>
	<td>
	Initial version
	</td>
	<td>
	<ul>
	<li>Needs to be reviewed! Use at your own risk!
	<li>Need to add explanation for adding own dialog box for predefining values.
	<li>Explanatory text for the use of the NetBeans APIs to be added.
	<li>Check for copy-paste errors.
	<li>Need to add more Javadoc links, for NetBeans API classes in the code.


	</ul>
	</td>
	</tr>

	<tr>
	<td>
	2
	</td>
	<td>
	30 November 2005
	</td>
	<td>
	<li>Changed the ZIP file because of problems (see <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=69571">Issue 69571</a>).
	<li>Removed hyphens and changed screenshots.
	</td>
	<td>
	All other issues from above must still be done.
	</td>
	</tr>
	<tr>
	<td>
	3
	</td>
	<td>
	8 December 2005
	</td>
	<td>
	<li>Fixed reopened issue <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=69571">Issue 69571</a>
	<td>
	All other issues from above must still be done.
	</td>
	</tr>
	<tr>
	<td>
	4
	</td>
	<td>
	22 August 2006
	</td>
	<td>
	<li>Minor tweaks.
	<td>
	All other issues from above must still be done.
	<br>Discovered that the editor support file is missing in the tutorial,
	but not in the module that you can download from the top of the file.
	<br>Discovered that there are several gaps and tbds in this tutorial.
	</td>
	</tr>
	<tr>
	<td>
	5
	</td>
	<td>
	30 May 2007
	</td>
	<td>
	Began updating this tutorial for 6.0.
	</td>
	<td>
	...
	</td>
	</tr>
	<tr>
	<td>
	6
	</td>
	<td>
	5 November 2008
	</td>
	<td>
	Began & completed updating this tutorial for 6.5.
	<p>Main changes:
	<ul>
	<li>New sample download link to Plugin Portal.
	<li>Rewritten code to use <tt>layer.xml</tt> registration.
	<li>Instead of JBoss palette and snippets for JBoss XML file,
	created a palette for Java source files, which is now
	possible because editor and palette do not need to be
	in the same module. Therefore sections like
	'Recognizing the New File Type' are not necessary (except
	if the palette is for a new file type, in which case
	the File Type Module tutorial should first be used).
	<li>Omitted the code for creating the palette item, because
	it is already described in the Code Snippet Module Tutorial.
	</ul>
	</td>
	<td>
	3 August 2009
	</td>
	<td>
	Fixed broken element tags so that formatting is now correct.
	</td>
	</tr>
	</tbody>
	</table>-->
	</body>
	</html>