Writing POV-Ray Support for NetBeans IV - Providing Project Templates

Tim Boudreau
6 June 2006

Feedback

This is a DRAFT!

This is a continuation of the tutorial for building POV-Ray support for NetBeans. If you have not read the first or second and third parts of this tutorial, you may want to start there.

Project Templates

We left off with a module that let us open POV-Ray projects, and basic support for POV-Ray files, but no way to create a new POV-Ray project.

So the first step is to add the ability to use the New Project Wizard to create POV-Ray projects. NetBeans 5.0 and up has the ability to embed a project in a module as a zip file, and add the necessarily configuration and code to make it available from the New Project wizard and unpack it in a directory of the user's choice. We will make use of that functionality to create our project templates.

First we need to have a project to zip up, so we will create that by hand. You can do this in NetBeans, just by creating the appropriate folders and files.

1. First create a new package in the Povray Projects project, org.netbeans.examples.modules.povproject.templates. This will simply help us keep the sources more organized.

2. Switch to the Files tab in the IDE and find the root folder for the Povray Projects project
3. Create the following directory structure underneath that directory:
   • templates/ - a root directory for our template projects
     • EmptyPovrayProject/ - Base directory for an empty project
       • images/
       • pvproject/
         • project.properties
       • scenes/
         • SamplePovrayProject.pov
     • SamplePovrayProject/ - Base directory for an project with sample .pov files
       • images/
       • pvproject/
         • project.properties
       • scenes/
         • SamplePovrayProject.pov

We should have some content for the sample POV-Ray project's file. You can copy and paste the initial content (a 3D model of the NetBeans logo) from this file.

Now we are ready to add our sample projects - but here we have to cheat just a little: the IDE will only package up a sample project that it has open, and in our development IDE we don't have support for POV-Ray projects, so our hand-created projects won't be recognized. But, we already have a module that provides support for POV-Ray projects available. So we will cheat just a little bit and use that to fool it into embedding our new POV-Ray projects in our module:

1. Right click the module suite, and choose Run

2. When the IDE is started, open templates/EmptyPovrayProject and Templates/SamplePovrayProject in that instance of the IDE

3. Now, open the Povray Projects module in the IDE as well.

4. Expand the Povray Projects module and right click the package org.netbeans.examples.modules.povproject.templates and choose New > File/Folder

5. In the New File Dialog, select NetBeans Module Development > J2SE Library Descriptor (this is where we're cheating - a POV-Ray project has nothing to do with J2SE, but the IDE doesn't care). Press Enter or click Next.

6. On the next page of the wizard, select EmptyPovrayProject from the combo box - this is what we will package up. Click Next or press Enter.

7. Now you are prompted for a name. Enter "EmptyPovrayProject" for the Template Name, and "Empty Povray Project" for the display name. Select General as the category (we can create our own POV-Ray category later), and click Finish or press Enter.

8. Now repeat the above steps for templates/SamplePovrayProject, calling it Sample Povray Project.

9. Close the copy of NetBeans that has our modules installed - it's done its job for now

The above steps created a number of files on disk - there are two new zip files in our module that are zipped copies of the projects. The following new files were created. Some will be deleted - our two templates can share wizard code for instantiating them from the New Project wizard:

• povproject/
  • EmptyPovrayProjectProject.zip
  • SamplePovrayProjectProject.zip
  • templates/
    • EmptyPovrayProjectDescription.html Description that will be shown when the user selects the project in the New Project wizard
    • EmptyPovrayProjectPanelVisual.form Form file for the panel in the wizard that lets the project be named, which we can customize
    • EmptyPovrayProjectPanelVisual.java Corresponding Java file for the template
    • EmptyPovrayProjectWizardIterator.java A "wizard iterator" which provides the additional steps in the wizard after selecting the template
    • EmptyPovrayProjectWizardPanel.java A wrapper object that delays creating EmptyProjectPanelVisual until the user navigates to that page in the wizard
    • SamplePovrayProjectDescription.html Description that will be shown when the user selects the sample project in the New Project wizard
    • SamplePovrayProjectPanelVisual.java can be deleted
    • SamplePovrayProjectWizardIterator.java can be deleted
    • SamplePovrayProjectWizardPanel.java can be deleted

The layer.xml file has also been modified, to register these two projects so they are added to the New Project wizard. The following code has been added to the layer.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.1//EN" "http://www.netbeans.org/dtds/filesystem-1_1.dtd">
<filesystem>
    <folder name="Templates">
        <folder name="Project">
            <folder name="Standard">
                <file name="EmptyPovrayProjectProject.zip"
                        url="EmptyPovrayProjectProject.zip">
                    <attr name="SystemFileSystem.localizingBundle"
                        stringvalue="org.netbeans.examples.modules.povproject.templates.Bundle"/>
                    <attr name="instantiatingIterator"
                        methodvalue="org.netbeans.examples.modules.povproject.templates.EmptyPovrayProjectWizardIterator.createIterator"/>
                    <attr name="instantiatingWizardURL"
                        urlvalue="nbresloc:/org/netbeans/examples/modules/povproject/templates/EmptyPovrayProjectDescription.html"/>
                    <attr name="template" boolvalue="true"/>
                </file>
                <file name="SamplePovrayProjectProject.zip"
                        url="SamplePovrayProjectProject.zip">
                    <attr name="SystemFileSystem.localizingBundle"
                        stringvalue="org.netbeans.examples.modules.povproject.templates.Bundle"/>
                    <attr name="instantiatingIterator"
                        methodvalue="org.netbeans.examples.modules.povproject.templates.SamplePovrayProjectWizardIterator.createIterator"/>
                    <attr name="instantiatingWizardURL"
                        urlvalue="nbresloc:/org/netbeans/examples/modules/povproject/templates/SamplePovrayProjectDescription.html"/>
                    <attr name="template" boolvalue="true"/>
                </file>
            </folder>
        </folder>
    </folder>
</filesystem>

The above XML looks like a lot to chew on, but it's relatively simple. For each template, we declare a file in Templates/Project/Standard - this means that these files will be findable at runtime in the System Filesystem (a kind of virtual configuration data store composed from XML layer files, which uses the same Filesystem interface you use in NetBeans modules to access files on disk). The attributes are key value pairs that have some special meanings when applied to a template:

• SystemFilesystem.localizingBundle — A pointer to a resource bundle (properties file) that contains a localized, human-friendly, translatable name for the file
• instantiatingIterator — This is a pointer to a static method that can create a WizardIterator - a factory for additional pages in the New Project wizard
• instantiatingWizardURL — This is a pointer to an html file, which contains a description of the template, which will appear in the New Project dialog when the user selects our template

Since these templates are nearly identical, we don't need separate classes for the New Project wizard for each one - one class will do nicely for both templates. So we will make one change to the layer file, and delete some of the classes that were generated:

1. Open layer.xml in the code editor. Find the line:

   <attr name="instantiatingIterator"
       methodvalue="org.netbeans.examples.modules.povproject.templates.EmptyPovrayProjectWizardIterator.createIterator"/>
       

   and copy it to the clipboard

2. Find the equivalent line in the definition for SamplePovrayProjectProject.zip, which declares the "instantiatingIterator" and select it

3. Paste the line on the clipboard over this line, replacing it, so the line declaring the "instantiatingIterator" is the same for both entries.

4. Delete SamplePovrayProjectPanelVisual.java, SamplePovrayProjectWizardIterator.java and SamplePovrayProjectWizardPanel.java

Modifying the Build Script

Our initial sample projects are probably not in their final form, so it would be nice to have the build script automatically rebuild the zip files of the sample projects whenever we build the Povray Projects module - that way we can simply modify the samples at will, and whenever we do a build they will be up-to-date. So we'll make a few changes to the build script:

1. Add the following targets to the Ant build script for Povray Projects:

       <target name="netbeans" depends="package-samples,projectized-common.netbeans"/>
   
       <target name="package-samples">
           <delete file="${basedir}/src/org/netbeans/examples/modules/povproject/EmptyPovrayProjectProject.zip"/>
           <delete file="${basedir}/src/org/netbeans/examples/modules/povproject/SamplePovrayProjectProject.zip"/>
           <zip compress="9" basedir="templates/EmptyPovrayProject/"
               zipfile="${basedir}/src/org/netbeans/examples/modules/povproject/EmptyPovrayProjectProject.zip"/>
           <zip compress="9" basedir="templates/SamplePovrayProject/"
               zipfile="${basedir}/src/org/netbeans/examples/modules/povproject/SamplePovrayProjectProject.zip"/>
       </target>
   
       

If we were using a version control such as CVS to store our source code, now would be a good time to mark the two zip as ignored (add them to .cvsignore or equivalent).

Next Steps

In the next section we will create the API needed for communication between our two current modules.