| <!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 NetBeans Platform 7.2</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/72/netbeans-stamp.gif" 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 6 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> |