Custom templates?

[krancour]

Does anyone know if it's possible to define and use custom project templates with the New Template Project wizard in STS? And if so, how?

I've spent a bit of time trying to figure out how to do this (or if it's even possible) and I'm not getting anywhere. Searching isn't turning up much either.

Any help is appreciated.

[Martin Lippert]

Hi Kent!

Unfortunately we don't have a good documentation on that at the moment, but we are working on that. I will let you know when there is something for you to try, ok?

Cheers,
-Martin

[krancour]

Thanks, Martin. When you say you're working on it- you're working on adding this feature? Or working on documenting it?

[Martin Lippert]

This should already be possible, I am currently working on a small example that describes how to do this. Stay tuned...

[Martin Lippert]

Custom Project Templates in STS

STS provides the New Spring Template Project wizard. Uses this wizard, the user can see a number of project templates, choose one and let the wizard create a complete project, based on that template description.

In order to create your own project templates for STS, you need to do the following at the moment:

1. Build a new bundle that contributes a new resources extension to STS

STS creates the list of available project templates by downloading and reading resource XML files. To let STS know where those resource files are located, you need to contribute them to STS via an extension.

So the first step is to create a new and empty plugin project. You don't need Java code in there, so don't create this as a Java project. Just create a new plugin project, deselect the Java options in the wizard and you are done.

Now define the extension within that plugin project. Create a plugin.xml by selecting the extension tab, when you have the manifest editor open (double clicking on the META-INF/MANIFEST.MF). You define the extension my modifying the plugin.xml to look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>

   <extension
         point="com.springsource.sts.core.resources">
      <url
            id="content.descriptors"
            value="%content.descriptor.urls">
      </url>
   </extension>

</plugin>

This defines a contribution to the STS extension point "com.springsource.sts.core.resources" and overrides the default value for the "content.descriptors" id with your new value. This new value should contain all the URLs from all templates you would like to see within the STS wizard. In this case, we don't put the URLs in here directly, but we externalize them into a separate properties file. THIS IS NEEDED for multiple URLs, as you will see.

The next step is to create a properties file called "bundle.properties" inside your plugin, and you should put that into a directory called "OSGI-INF/I10n/". This properties file should look like this:

content.descriptor.urls = http://dist.springsource.com/release...riptors.xml\n\
file:///Users/mlippert/template-contribution/descriptor.xml

As you can see, I put the original STS value in there to keep the STS default templates available and added my own URL to my (in this case local) descriptor.xml file. ´so if you would like to use just a local file, you can go ahead with this approach. In the case where you would like to distribute your new template across your company, having the descriptor.xml file being served as a http resources would make sense. Please note that the URLs are separated by a "\n".

Now you are pretty much done with the new plugin for STS. You can export that and put the resulting JAR file into the "dropins" directory of your STS installation. Take care that the build.properties have META-INF, OSGI-INF, and plugin.xml checked to be included for the binary build.

(I attached an example plugin project for this, take a look at the attachments.)

2. Build the descriptor.xml file

The URL that you added to the STS extension in the previous step points to a descriptor.xml file. This file should look like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<descriptors> 
  <descriptor id="org.test.mynewtemplate" kind="template" local="false" name="Mein neues Template" size="998877" url="file:///Users/mlippert/template-contribution/test-template-1.0.0.zip" version="1.0.0"> 
    <description>My brand new template contribution for this hacky stuff etc.</description> 
  </descriptor> 
</descriptors>

As you can see, I put some random stupid examples in there, you should replace that with your own ids. Please choose:

• your own ID for the template ("org.test.mynewtemplate" in the example)
• your own name for the template ("Mein neues Template"), this will show up in the list of the wizard
• your own URL to point to the ZIP file for the template
• don't forget to set the correct size of the ZIP file in the "side" attribute
• description: some more text to tell the user what your template is all about

3. Build the real template

Now you need to create that ZIP file that we referenced from the descriptor.xml file. This ZIP file should contain three files in its root directory:

• template.xml
• template.zip
• wizard.json

Lets take a look at the first one, template.xml:

<template>
	<descriptor id="org.test.mynewtemplate"
		name="Mein neues Template"
		kind="template"
		version="1.0.0">
		<description>
			My brand new template contribution for this hacky stuff
		</description>
	</descriptor>
	<project path="template.zip"/>
	<json path="wizard.json"/>
</template>

It contains the same id, name, and description for the template than the descriptor.xml, also the same version and the kind "template". In addition to that it also contains the reference to the template.zip file and the wizard.json file. So this is the place where you define those two other files.

The wizard.json file contains the description that is used to create and handle the UI of the wizard for this template specifically. In my example the wizard.json file looks like this:

{
	"info" : {
		"elements" : {
			"element" :	[
				{
					"name" : "topLevelPackage",
					"description" : "Please specify the top-level package e.g. com.mycompany.myapp",
					"type" : "java.lang.String",
					"page" : 0,
					"required" : true,
					"pattern" : "\\w+\\.\\w+(\\.\\w+)+",
					"replaceKind" : "topLevelPackage"
				}
			]
		},

		"topLevelPackage" : "mytld.mycompany.myapp.mysubsystem",

		"projectName" : "projectName",

		"pages" : {
			"page" : [
					{
					"order" : 0,
					"description" : "Project Settings"
				}
			]
		}
	}
}

I don't go into the details here, but this is basically the information for the wizard UI. It contains the elements that the user can type in within the wizard and that are used to create the actual project (for example the top level packages).

The last part is the actual project that you would like to instantiate if the user chooses your template. All you need to do here is to create the project yourself and name the top-level packages the way you defined it in the wizard.json (in this case mytld.mycompany.myapp.mysubsystem). In the example that I attached to this the template project resides in the root directory called "template" and contains:

• .classpath
• .project
• .settings
• .springBeans
• pom.xml
• src directory containing the project layout and some predefined source code

That's it!

Please note: Once you have downloaded the zip file of your new template into STS (this is done automatically after you have chosen it from the list and pressed return), STS will re-use the downloaded file the next time. So if you chance your template, take care to set a newer version number to it. Otherwise STS will not pick-up your changed one.

[screedon]

Hi Martin,

when you talk about wizard.json you say "I don't go into the details here, but this is basically the information for the wizard UI", so can you point me to where I can get this detail.
I would also be interested in knowing how the values typed in the wizard are used to modify the template contents during project creation time, e.g. how the topLevelPackage typed by the user replaces the one specified in the template

Thanks
Sean

[Martin Lippert]

Hey Sean!

Terry will be able to help you, she comes back to work mid of next week. She will be able to spend some time with you to chat with you about all the details and help you with the templates. Hope that works for you.

-Martin

[screedon]

Thanks Martin,

that would be great,

Regards,
Sean

[thon]

Hi Sean,

Sorry we don't have better documentation online. Here is a snippet about the json file that I was working on before that could help. Let me know if you need more information.

An element is a field in the wizard. For each field you have to specify the name, description, type of the input (currently only java.lang.String and java.lang.Boolean are supported), the page number of the page that the element should appear in.

Some optional entry for a field are:
"pattern" - If you only expect user to enter a specific string pattern, you can specify a regular expression in the pattern entry
"order" - It specifies the order in which the element appears, by default the order is as specfied by the order in which the elements are defined
"required" - By default a field is not required to be filled out
"replaceKind" - There are 3 replacement kinds: projectName, topLevelPackage and token. ProjectName specifies that the field is the name of the project. By default project name is specified by the field named projectName. You should specify the replace kind explicitly if you want the project name to be defined by a field of a different name. Similary topLevelPackage specifies the name of the top level package. Note that a simple string token replacement is used to transform the zipped template project to the project that will be created for the user. Make sure the tokens that are used to specify package names are unique and renaming them will not cause a problem.
Finally the token type is the default replace kind for all fields (unless the field is named packageName or topLeveLPackage). This simply means any occurrence of the field name will be replaced by the user input. As an example ("name" : "myCompanyName") all occurences with myCompanyName in the java, properties, html, .... will be replaced by the user entry for that field.
"errorMessage" - the message that will be displayed if a required field is not filled out or if "pattern" is specified, the message will be displayed when the pattern is not satisfied.

The topLevelPackage element specifies the top level package of the zipped project. This information is needed for proper renaming of top level package to the user entry. Note that if the top level package specified in this level has different length than the user input, only the minimum length of the two package names will be renamed. You should specify a pattern to ensure users enter the right length if that is a problem.

The projectName element specifies the token that holds the project name in the zipped project. By default "projectName" is used for that token. The project name is now present by default (along with project location selection), so an additional UI element is not necessary for project name.

A page specifies the ordering and the description of each wizard page.

Cheers,
Terry

[Martin Lippert]

Hey!

I am sorry, but I don't understand your question and I don't think it is related to the topic of this thread at all. Please ask this question in a new thread and in the right forum for this.

HTH,
Martin