Simple Project Templates
- by Geertjan
The NetBeans sources include a module named "simple.project.templates":
In the module sources, Tim Boudreau turns out to be the author of the code, so I asked him what it was all about, and if he could provide some usage code. His response, from approximately this time last year because it's been sitting in my inbox for a while, is below.
Sure - though I think the javadoc in it is fairly complete. I wrote
it because I needed to create a bunch of project templates for
Javacard, and all of the ways that is usually done were grotesque and
complicated. I figured we already have the ability to create files from
templates, and we already have the ability to do substitutions in
templates, so why not have a single file that defines the project as a
list of file templates to create (with substitutions in the names) and
some definitions of what should be in project properties. You can also add files to the project programmatically if you want.Basically,
a template for an entire project is a .properties file. Any line which
doesn't have the prefix 'pp.' or 'pvp.' is treated as the definition of
one file which should be created in the new project. Any such line
where the key ends in * means that file should be opened once the new
project is created. So, for example, in the nodejs module, the
definition looks like:
{{projectName}}.js*=Templates/javascript/HelloWorld.js
.npmignore=node_hidden_templates/npmignore
So, the first line means:
- Create a file with the same name as the project, using the HelloWorld template
- I.e. the left side of the line is the relative path of the file to
create, and the right side is the path in the system filesystem for the
template to use
- If the template is not one you normally want users to see,
just register it in the system filesystem somewhere other than
Templates/ (but remember to set the attribute that marks it as a
template)
- Include that file in the set of files which should be opened in the editor once the new project is created.
To actually create a project, first you just create a new ProjectCreator:
ProjectCreator gen = new ProjectCreator( parentFolderOfNewProject );
Now, if you want to programmatically generate any files, in addition to those defined in the template, you can:
gen.add (new FileCreator("nbproject", "project.xml", false) {
public DataObject create (FileObject project, Map<String,String> substitutions) throws IOException {
...
}
});
Then
pass the FileObject for the project template (the properties file) to
the ProjectCreator's createProject method (hmm, maybe it should be the
string path to the project template instead, to save the caller trouble
looking up the FileObject for the template). That method looks like
this:
public final GeneratedProject createProject(final ProgressHandle
handle, final String name, final FileObject template, final
Map<String, String> substitutions) throws IOException {
The name parameter should be the directory
name for the new project; the map is the strings you gathered in the
wizard which should be used for substitutions. createProject should be
called on a background thread (i.e. use a ProgressInstantiatingIterator
for the wizard iterator and just pass in the ProgressHandle you are
given).
The return value is a GeneratedProject object, which
is just a holder for the created project directory and the set of
DataObjects which should be opened when the wizard finishes.
I'd love to see simple.project.templates moved out of the javacard
cluster, as it is really useful and much simpler than any of the stuff
currently done for generating projects. It would also be possible to do
much richer tools for creating projects in apisupport - i.e. choose (or
create in the wizard) the templates you want to use, generate a
skeleton wizard with a UI for all the properties you'd like to
substitute, etc.
Here is a partial project template from Javacard -
for example usage,
see org.netbeans.modules.javacard.wizard.ProjectWizardIterator in
javacard.project (or the much simpler one in contrib/nodejs). #This properties file describes what to create when a project template is#instantiated. The keys are paths on disk relative to the project root.
#The values are paths to the templates to use for those files in the system#filesystem. Any string inside {{ and }}'s will be substituted using properties#gathered in the template wizard.#Special key prefixes are
# pp. - indicates an entry for nbproject/project.properties# pvp. - indicates an entry for nbproject/private/private.properties
#File templates, in format [path-in-project=path-to-template]META-INF/javacard.xml=org-netbeans-modules-javacard/templates/javacard.xmlMETA-INF/MANIFEST.MF=org-netbeans-modules-javacard/templates/EAP_MANIFEST.MF
APPLET-INF/applet.xml=org-netbeans-modules-javacard/templates/applet.xmlscripts/{{classnamelowercase}}.scr=org-netbeans-modules-javacard/templates/test.scrsrc/{{packagepath}}/{{classname}}.java*=Templates/javacard/ExtendedApplet.java
nbproject/deployment.xml=org-netbeans-modules-javacard/templates/deployment.xml#project.properties contentspp.display.name={{projectname}}pp.platform.active={{activeplatform}}
pp.active.device={{activedevice}}pp.includes=**pp.excludes=
I will be using the above info in an upcoming blog entry and provide step by step instructions showing how to use them. However, anyone else out there should have enough info from the above to get started yourself!
