<!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 Project Sample Module Tutorial for the NetBeans Platform</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 creating project samples."/> | |
<!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. --> | |
<!-- Use is subject to license terms.--> | |
</head> | |
<body> | |
<h1>NetBeans Project Sample Module Tutorial</h1> | |
<p>This tutorial demonstrates how to create a module that adds a sample | |
to the New Project wizard. The sample could function either as an example | |
to the user or as a new project template that provides the basic files needed to | |
get started working on a technology of some kind.</p> | |
<p><strong class="notes">Note: </strong>This document uses NetBeans Platform 7.2 and | |
NetBeans IDE 7.2. If you | |
are using an earlier version, see <a href="71/nbm-projectsamples.html">the previous version | |
of this document</a>.</p> | |
<p><b>Contents</b></p> | |
<p><img src="../images/articles/74/netbeans_stamp_74_73_72.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 7.2" title="Content on this page applies to NetBeans IDE 7.2"/></p> | |
<ul class="toc"> | |
<li><a href="#into">Introduction to Project Samples</a></li> | |
<li><a href="#creatingthemoduleproject">Creating the Module Project</a></li> | |
<li><a href="#creatingandgettingtoknowthemainfiles">Bundling the Sample Application</a></li> | |
<li><a href="#building">Building and Installing the Module</a> | |
<ul> | |
<li><a href="#installing-the-nbm">Installing the NetBeans Module</a></li> | |
<li><a href="#using-the-nbm">Using the NetBeans Module</a></li> | |
<li><a href="#creating-the-nbm">Creating a Shareable Module Binary</a></li> | |
</ul></li> | |
<li><a href="#tweaking">Tweaking the Module</a> | |
<ul> | |
<li><a href="#icon">Changing the Icon</a></li> | |
<li><a href="#category">Changing the Category</a></li> | |
<li><a href="#description">Changing the Description</a></li> | |
<li><a href="#panel">Adding a Panel</a></li> | |
<li><a href="#sources">Updating the Sources</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 7.2 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 7 or above</td> | |
</tr> | |
</tbody> | |
</table> | |
<h2><a name="intro"></a>Introduction to Project Samples</h2> | |
<p>Using two wizards in the IDE—the New Module Project wizard and the | |
New Project Template wizard—you can very easily create a module that | |
contains your technology's project samples. No coding of any kind is needed in | |
order to do this. The wizards do all the work for you. In fact, if you find yourself | |
doing any coding at all, you are possibly doing something wrong. Coding should only | |
be necessary in a small set of corner cases.</p> | |
<p>When you complete this tutorial, you will have a module that contains | |
your samples. The intended users of your samples | |
can then simply use the Plugin Manager to install the module. As a result, the samples | |
will appear in the New Project wizard.</p> | |
<p>At the end of this tutorial, the New Project wizard will contain a new sample, | |
called "My Sample Application":</p> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-4.png" alt="changing the description"/></p></li> | |
<p>In addition to showing how to create a module containing a sample, | |
you will be instructed on some ancillary topics, such as how to change | |
the icon and description in the New Project wizard, and how to regenerate | |
the sample after modifying its sources.</p> | |
<h2 class="tutorial"><a name="creatingthemoduleproject"></a>Creating the Module Project</h2> | |
<p>We begin by working through the New Module Project | |
wizard. At the end of it, we will have a basic | |
source structure, with some default files, that | |
every NetBeans module requires.</p> | |
<div class="indent"> | |
<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>AdditionalSamples</tt> in the Project Name field. | |
Change the Project Location to any directory on your computer. Click Next.</li> | |
<li>In the Basic Module Configuration panel, type <tt>org.myorg.additionalsamples</tt> | |
in Code Name Base. Click Finish.</li> | |
</ol> | |
</div> | |
<p> The IDE creates the <tt>AdditionalSamples</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="creatingandgettingtoknowthemainfiles"></a>Bundling the Sample Application</h2> | |
<p>Now that we have a module project, which gives us our source structure, | |
we simply run through another wizard that will bundle our sample. You simply | |
need to select it in the wizard and then the wizard will | |
generate all the required classes and registration | |
details for you.</p> | |
<div class="indent"> | |
<ol> | |
<li>Right-click the project node and | |
choose New > Other. Under Categories, select NetBeans Module Development. Under Projects, | |
select Project Template. Click Next.</li> | |
<li><p>In the Select Project panel, select the project | |
that you want to bundle as a sample, as shown below.</p> | |
<br/> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-5.png" alt="changing the description"/></p> | |
<br/> | |
<p><b class="notes">Note:</b> Only projects that | |
are open in the IDE are shown in | |
the Project drop-down above. To bundle | |
an external project as a sample, use the | |
Browse button to locate it in your | |
filesystem.</p> | |
<br/> | |
<p>Click Next.</p></li> | |
<li><p>In the Name and Location panel, type <tt>MySampleApplication</tt> as the template name, | |
type <tt>My Sample Application</tt> as the display name, | |
and select Samples | Java in the Category drop-down, as | |
shown below:</p> | |
<br/> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-6.png" alt="Name and location panel."/></p> | |
<br/></li> | |
<li>Click Finish.</li> | |
</ol> | |
</div> | |
<p> The IDE creates the following:</p> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-2.png" alt="Name and location panel."/></p></li> | |
<ul> | |
<li><tt>MySampleApplication.png.</tt> Image copied from the icon of the sample.</li> | |
<li><tt>MySampleApplicationDescription.html.</tt> Description text to be displayed in the | |
New Project dialog's description field.</li> | |
<li><tt>MySampleApplicationPanelVisual.</tt> | |
<br><tt>MySampleApplicationWizardIterator.java.</tt> | |
<br><tt>MySampleApplicationWizardPanel.java.</tt> A <tt>JPanel</tt>, with a supporting wizard class, and an iterator | |
used in the New Project wizard to create the sample. You do not need | |
to understand how these work, unless you want to. Later in this tutorial, | |
these classes are discussed, although they are not necessary to understand | |
in most scenarios involving the creation of project samples.</li> | |
<li><tt>MySampleApplicationProject.zip.</tt> A ZIP file containing your sample.</li> | |
</ul> | |
<!-- ======================================================================================= --> | |
<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="installing-the-nbm"></a>Installing the NetBeans Module</h3> | |
<p>In the Projects window, right-click the <tt>AdditionalSamples</tt> project and choose Install/Reload | |
in Target Platform.</p> | |
<p>The module is built and installed in a new instance of NetBeans IDE or | |
other application created on the NetBeans Platform. The application opens so that you | |
can try out the functionality provided by your new module.</p> | |
<h3 class="tutorial"><a name="using-the-nbm"></a>Using the NetBeans Module</h3> | |
<p>In this section, we take on the role of the user of our sample. After a user | |
installs our module, either explicitly or because it is part of the application | |
they started up, they will typically take the steps outlined below.</p> | |
<div class="indent"> | |
<ol> | |
<li><p>Choose File > New Project (Ctrl-Shift-N). The New Project wizard opens and displays | |
the new project sample:</p> | |
<br/> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-4.png" alt="changing the description"/></p></li> | |
<li><p>Select the new project sample and click Next. | |
Type a name in the project name field and define a project location.</p> | |
<br/> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-4a.png" alt="changing the description"/></p></li> | |
<p>Click Finish. | |
The Projects window opens and | |
displays the newly created project sample.</p></li> | |
</ol> | |
</div> | |
<h3 class="tutorial"><a name="creating-the-nbm"></a>Creating a Shareable Module Binary</h3> | |
<p>To make our sample available to our users, we need to create an NBM file, which | |
is a binary NetBeans module file, containing our sample.</p> | |
<div class="indent"> | |
<ol> | |
<li><p>In the Projects window, right-click the <tt>AdditionalSamples</tt> | |
project and choose Create NBM. The NBM file is created | |
and you can view it in the Files window (Ctrl-2):</p> | |
<br/> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-7.png" alt="changing the description"/></p></li> | |
<li>Make it available to others via, for example, e-mail. Or create your own NetBeans | |
Update Center and publish it there. Or publish it in the <a href="http://plugins.netbeans.org/PluginPortal/">NetBeans Plugin Portal</a>.</li> | |
</ol> | |
</div> | |
</div> | |
<!-- ======================================================================================= --> | |
<h2><a name="tweaking"></a>Tweaking the Sample</h2> | |
<p>In this section, we perform some typical tasks | |
that you might want to perform after completing | |
the New Project Template wizard, in order to finetune | |
your sample. For example, you might want to change the | |
sample's icon, description, and similar items.</p> | |
<div class="indent"> | |
<h3 class="tutorial"><a name="icon"></a>Changing the Icon</h3> | |
<p>Optionally, you can change the icon you chose when | |
you worked through the New Project Template wizard.</p> | |
<p> | |
Within the annotation at the top of the iterator class, | |
the <tt>iconBase</tt> attribute reflects your icon choice:</p> | |
<pre class=examplecode>@TemplateRegistration( | |
folder = "Project/Samples/Standard", | |
displayName = "#MySampleApplication_displayName", | |
description = "MySampleApplicationDescription.html", | |
<b>iconBase = "org/myorg/additionalsamples/MySampleApplication.png",</b> | |
content = "MySampleApplicationProject.zip")</pre> | |
<p>Manually change the icon, by adding it to your module, | |
and changing its name and location in the annotation | |
shown above.</p> | |
</p> | |
<h3 class="tutorial"><a name="category"></a>Changing the Category</h3> | |
<p>When we used the New Project Template wizard, we assigned the | |
sample to a category. Afterwards, we can put it in a different category, | |
using the <tt>folder</tt> attribute to do so:</p> | |
<p> | |
Within the annotation at the top of the iterator class, | |
the <tt>iconBase</tt> attribute reflects your icon choice:</p> | |
<pre class=examplecode>@TemplateRegistration( | |
<b>folder = "Project/Samples/Standard"</b>, | |
displayName = "#MySampleApplication_displayName", | |
description = "MySampleApplicationDescription.html", | |
iconBase = "org/myorg/additionalsamples/MySampleApplication.png", | |
content = "MySampleApplicationProject.zip")</pre> | |
</p> | |
<h3 class="tutorial"><a name="description"></a>Changing the Description</h3> | |
<p>Next, we can change the sample's description, which is shown | |
in the New Project wizard. As with the icon, a default | |
description is provided when you create a module containing | |
a sample. However, you can easily change that description.</p> | |
<div class="indent"> | |
<ol> | |
<li><p>Open the file shown below and notice the default text shown in the editor:</p> | |
<br/> | |
<p><img alt="" src="../images/tutorials/mysample/72/proj-temp-3.png" alt="changing the description"/></p></li> | |
<li>Change the text, reinstall the module, and notice the changed | |
description in the New Project wizard.</li> | |
</ol> | |
</div> | |
<h3 class="tutorial"><a name="description"></a>Adding a Panel</h3> | |
<p>In the previous section, we changed the iterator, | |
which resulted in a different panel being shown. Possibly, | |
however, there is no existing iterator to cater to your | |
specific needs. In this section, we learn how to | |
add a new panel to the wizard. We do this by reusing the | |
iterator that the New Project Template wizard creates | |
for us.</p> | |
<div class="indent"> | |
<ol> | |
<li>Use the Wizard wizard to create a new wizard panel | |
which, just like the panel created by the New Project Template | |
wizard, consists of a <tt>JPanel</tt> and a wizard class.</li> | |
<li>Instantiate the new wizard panel in the iterator's | |
<tt>createPanels()</tt> method, as shown here: | |
<pre class=examplecode>private WizardDescriptor.Panel[] createPanels() { | |
return new WizardDescriptor.Panel[] { | |
<b>//This is the wizard panel, created by the | |
//New Project Template wizard:</b> | |
new MySampleApplicationWizardPanel() | |
<b>//This is the new wizard panel, created by the | |
//New Wizard wizard:</b> | |
//new MySampleApplicationWizardPanel1() | |
}; | |
}</pre> | |
<p>You only need to add your new wizard panel to the method | |
above, and then it will be instantiated when the | |
sample's wizard is invoked by the user in the New | |
Project wizard.</p></li> | |
<li>Finally, you need to add a new string | |
to the iterator's <tt>createSteps()</tt> method, | |
so that your new wizard panel is accompanied | |
by a string in the left sidebar of the wizard: | |
<pre class=examplecode>private String[] createSteps() { | |
return new String[] { | |
NbBundle.getMessage(MySampleApplicationWizardIterator.class, "LBL_CreateProjectStep"), | |
<b>NbBundle.getMessage(MySampleApplicationWizardIterator.class, "LBL_CreateProjectStep1")</b> | |
}; | |
}</pre> | |
<p>You only need to add the line in bold above, and then | |
define the key/value pair in the <tt>Bundle.properties</tt> file.</p></li> | |
</ol> | |
</div> | |
<h3 class="tutorial"><a name="sources"></a>Updating the Sources</h3> | |
<p>When you change the sample's sources, how do you update the module | |
that bundles the sample? Do you need to recreate the module project, work | |
through the New Project Template wizard again, and then recreate the NBM file? | |
No. The only part of the sample module project that is impacted by changes | |
in the original sample's sources is the ZIP file. The ZIP file contains the sources, | |
and those are the only pieces that are affected when you make changes to the | |
original project. Hence, you simply need to recreate the ZIP file. To simplify this, | |
if you add the following Ant target to the <tt>build.xml</tt> file of | |
the project where you created the sources, you can regenerate the ZIP file from inside the IDE | |
and automatically have it copied to the sample module's source structure right away.</p> | |
<pre class=examplecode><target name="zipme" description="Zip the application to the sample project"> | |
<property name="build.classes.dir" location="/home/NetBeansProjects/AdditionalSamples"/> | |
<property name="examples" location="${build.classes.dir}/src/org/myorg/additionalsamples/"/> | |
<zip basedir="../MySampleApplication" destfile="${examples}/MySampleApplicationProject.zip"> | |
<exclude name="**/build/"/> | |
<exclude name="**/dist/"/> | |
<exclude name="**/nbproject/private/"/> | |
</zip> | |
</target></pre> | |
<p>In the above Ant target, the <tt>build.classes.dir</tt> property points to the location | |
of your sample module project, which is probably different in your scenario than is | |
indicated above. </p> | |
<p><b class="notes">Note:</b> We exclude some folders from the ZIP file, because these are | |
not needed in the sample module project and, in fact, would cause problems if they were | |
not excluded.</p> | |
</div> | |
<div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20Project%20Sample%20Module%207.2%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/">NetBeans API Javadoc</a></li> | |
</ul> | |
<!-- ======================================================================================== --> | |
<!-- | |
<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> | |
</tr> | |
<tr> | |
<td> | |
1 | |
</td> | |
<td> | |
9 July 2005 | |
</td> | |
<td> | |
Initial version | |
</td> | |
</tr> | |
<tr> | |
<td> | |
2 | |
</td> | |
<td> | |
10 July 2005 | |
</td> | |
<td> | |
<ul><li>Added the <tt>org.netbeans.modules.java.examples.J2SESampleProjectIterator</tt> wizard | |
as an alternative -- less strict than the web wizard. | |
<li>Expanded the Ant script that zips the project sample, so that it now excludes | |
build, dist, and nbproject/private folders. | |
</td> | |
</tr> | |
<tr> | |
<td> | |
3 | |
</td> | |
<td> | |
23 August 2005 | |
</td> | |
<td> | |
<ul><li>Completely rewrote the tutorial, because of the Project Template wizard. | |
<li>Questions: | |
<ul><li>What's the Category drop-down for? Select the category | |
in the New Project wizard where the sample will be registered, but | |
not implemented yet. | |
<li>Layer file indicates that no Bundle file exists, but it does.</ul> | |
<li>To do: | |
<ul><li>Add details on each of the created files (currently there's only a sentence, | |
this should be expanded). | |
<li>Explain relationship between generated files and resulting project template wizard. | |
<li>Add some post-processing customization steps (e.g., how to put the sample in a | |
different category in the New Project wizard). | |
<li>Add introductory sentences to each section. | |
<li>Info about XML layer file to be added.</ul> | |
</td> | |
</tr> | |
<tr> | |
<td> | |
4 | |
</td> | |
<td> | |
1 October 2005 | |
</td> | |
<td><ul> | |
<li>Worked through the tutorial with today's build and tweaked here and there. | |
<ul> <li>No major changes (except, used the Category to put the sample in a category). | |
<li>Created <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=65595">http://netbeans.org/bugzilla/show_bug.cgi?id=65595</a>. | |
</ul> | |
<li>To do: | |
<ul><li>Add details on each of the created files (currently there's only a sentence, | |
this should be expanded). | |
<li>Explain relationship between generated files and resulting project template wizard. | |
<li>Add some post-processing customization steps (e.g., how to put the sample in a | |
different category in the New Project wizard). | |
<li>Add introductory sentences to each section. | |
<li>Info about XML layer file to be added.</ul></ul> | |
</td> | |
</tr> | |
<tr> | |
<td> | |
5 | |
</td> | |
<td> | |
8 June 2007 | |
</td> | |
<td>Began updating to 6.0. Everything works, | |
just changed screenshots (which were still | |
from 5.0 in some cases, where icons were | |
different), removed references | |
to 5.x, replaced with 6.0, neatened things | |
up here and there. | |
<p>To do: | |
<ul> | |
<li>How to change the icon | |
<li>How to change the description | |
<li>How to change the category | |
<li>How to change the name | |
<li>How to regenerate the sample ZIP | |
<li>How and why to use the panel | |
<li>How to bundle external JARs and <tt>javadoc</tt> | |
<li>Multiple samples in same module | |
<li>Intro sentences in sections | |
<li>Better intro, with New Project wizard | |
screeshot, in the tutorial's introduction | |
</ul> | |
</td> | |
</tr> | |
<tr> | |
<td> | |
6 | |
</td> | |
<td> | |
April 2008 | |
</td> | |
<td>Began and completed updating updating to 6.1, | |
only new styles needed. In the meantime, | |
most of the above items have been added. | |
<p>To do: | |
<ul> | |
<li>Multiple samples in same module | |
<li>Discuss existing sample modules in the NetBeans | |
sources and how things have been done, and why. | |
</ul> | |
</td> | |
</tr> | |
<tr> | |
<td> | |
7 | |
</td> | |
<td> | |
1 November 2008 | |
</td> | |
<td>Fixed for 6.5, badge, table. To do: same as above.</td> | |
</tr> | |
<tr> | |
<td> | |
8 | |
</td> | |
<td> | |
July 2010 | |
</td> | |
<td>Fixed for 6.9, badge, table. To do: same as above.</td> | |
<td>Fixed error marks.</td> | |
</tr> | |
<tr> | |
<td> | |
9 | |
</td> | |
<td> | |
20 November 2011 | |
</td> | |
<td>Updating for 7.2.</td> | |
</tr> | |
<tr> | |
<td> | |
10 | |
</td> | |
<td> | |
30 December 2011 | |
</td> | |
<td>Updating for 7.1: Changed all screenshots, removed layer entries, | |
added annotations.</td> | |
- need to show how to remove the other templates | |
- need to show how to add a layer and tweak from there | |
- need to show that the annotation becomes a layer entry | |
</tr> | |
<tr> | |
<td> | |
11 | |
</td> | |
<td> | |
21 July 2012 | |
</td> | |
<td>Updating for 7.2: Changed all screenshots, to Windows.</td> | |
</tr> | |
</tbody> | |
</table>--> | |
</body> | |
</html> |