<!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><strong class="notes">Note: </strong>This document uses the NetBeans IDE 6.5 Release. If you | |
are using an earlier version, see <a href="60/nbm-palette-api2.html">the 6.0/6.1 version | |
of this document</a>. | |
<p><b>Contents</b></p> | |
<img src="../images/articles/65/netbeans-stamp65.gif" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 6.5" title="Content on this page applies to NetBeans IDE 6.5"> </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><a href="#coding-module">Creating the Component Palette and Code Snippets</a> | |
<ul> | |
<li><a href="#creating-palettes">Creating the Component Palette</a> | |
<li><a href="#adding-drag-handler">Adding a DragAndDropHandler</a> | |
<li><a href="#creating-snippets">Creating the Code Snippets</a> | |
</ul> | |
<li><a href="#registering-module">Registering the Module</a> | |
<ul> | |
<li><a href="#declaring-resources">Declaring the Resources</a> | |
<li><a href="#registering-resoucres">Registering the Resources</a> | |
</ul> | |
</li> | |
<li><a href="#reusing">Reusing Code Snippets from Other Palettes</a> | |
<li><a href="#building">Building and Installing the Module</a> | |
<ul> | |
<li><a href="#install-plugin">Installing and Using the Module</a> | |
<li><a href="#share-plugin">Creating a Shareable Module Binary</a> | |
</ul> | |
</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.5</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>. | |
<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>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>. | |
<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: | |
<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. | |
<p><li>In the New Project wizard, you will find the sample here:</p> | |
<p><img src="../images/tutorials/componentpalette/65-new-proj-dialog.png" alt="New Project dialog"> | |
<p><li>Complete the wizard and your project source structure will be as follows:</p> | |
<p><img src="../images/tutorials/componentpalette/65-new-proj-wiz.png" alt="Projects window initially"> | |
<p><li>Right-click the project node and choose Run. A new instance of the IDE opens and the module is installed. | |
<p><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> | |
<p><img src="../images/tutorials/componentpalette/65-open-java-file.png" border="1" alt="Open Java source file"> | |
<p><li>Drag the item into the Java source file and, when you drop the item, you will see the related customizer:</p> | |
<p><img src="../images/tutorials/componentpalette/65-customizer-in-java-file.png" alt="Customizer"> | |
<p><li>When you complete the customizer, you will have a new main method, together with the | |
comment you typed in the customizer:</p> | |
<p><img src="../images/tutorials/componentpalette/65-dropped-main-method.png" border="1" alt="Dropped main method"> | |
</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. | |
</div> | |
<br /> | |
<!-- ===================================================================================== --> | |
<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>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> | |
<br /> | |
<!-- ===================================================================================== --> | |
<h2><a name="coding-module"></a>Creating the Component Palette and Code Snippets</h2> | |
<br /> | |
<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. | |
<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> | |
<p><li>For each of the following APIs, click "Add...", | |
select the name from the Module list, and then click OK to confirm it:</p> | |
<p><img src="../images/tutorials/componentpalette/65-proj-props-1.png" alt="Setting dependencies"> | |
<p><li>Click OK to exit the Project Properties dialog box. | |
<p><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: | |
<ol> | |
<li>Right-click the <tt>JavaSourceFilePalette</tt> project node and | |
choose New > Java Class. Create a Java file called <tt>JavaSourceFileLayerPaletteFactory</tt>. | |
<p><li>Replace the default content of the <tt>JavaSourceFileLayerPaletteFactory.java</tt> file with the following: | |
<p><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> | |
</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: | |
<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. | |
<h3 class="tutorial"><a name="creating-snippets"></a>Creating the Code Snippets</h3> | |
<p>Each code snippet requires the following files: | |
<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>Optionally, a customizer where the user can type something that will be added to | |
the snippet, such as comments. | |
<li>A properties file that defines the labels and tooltips. | |
<li>A 16x16 pixel image for the 'Small Icon' display. | |
<li>A 32x32 pixel image for the 'Big Icon' display.</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>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. | |
</div> | |
<br /> | |
<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. | |
<ol> | |
<li>Add the following tags to the <tt>layer.xml</tt> file, between the <filesystem> tags: | |
<p><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> | |
<p><li>Add the following to the <tt>Bundle.properties</tt> file that is in the same package as | |
the <tt>layer.xml</tt> file: | |
<p><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. | |
</ol> | |
<br /> | |
<!-- ======================================================================================= --> | |
<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>Verify that the module is correctly installed by using it as | |
shown in <a href="#installing-sample">Installing the Sample</a>. | |
</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). | |
<li><p>Make the module available to others by uploading it to the <a href="http://plugins.netbeans.org">Plugin Portal</a>.</p | |
<p><li>The recipient can install the module by using the Plugin Manager. Choose Tools > Plugins | |
from the main menu. | |
</ol> | |
</div> | |
<br /> | |
<br> | |
<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> | |
<br style="clear:both;" /> | |
<!-- ======================================================================================== --> | |
<h2><a name="nextsteps"></a>Next Steps</h2> | |
<p>For more information about creating and developing NetBeans modules, see the following resources: | |
<ul> | |
<p><li><a href="https://netbeans.org/kb/trails/platform.html">Other Related Tutorials</a></li> | |
<p><li><a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans API Javadoc</a></li> | |
</ul> | |
<hr> | |
<!-- ======================================================================================== --> | |
<h2><a name="version"></a>Versioning </h2> | |
<p> | |
<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/issues/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/issues/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> | |
... | |
</td> | |
</tr> | |
</tbody> | |
</table> | |
</body> | |
</html> |