Template Developers Guide

Lazybones templates are simple zip files containing a directory structure and a bunch of files. How you create that zip file is up to you, but we’re going to use the build that was created for us. It handles both the packaging and publishing of templates, so we don’t have to worry about the details.

To get a project layout to begin with, we will use the gradle init command to create a simple Java application with Spock tests and a Gradle build. We are using a template naming convention of app type-language-test type-build tool to differentiate between templates, but you can use whatever convention that best suites your needs.

Create a new directory templates/java-gradle.

from a shell in this directory:

Gradle multi-project build layout with:

In java-gradle create these files. See below for information on their contents and also reference our sample in lazybones-templates/templates/java-gradle since they may be more complete than the basic content shown here.

Adding an empty .retain file in a template allows us to include empty directories in both a git repository and the template zip. The build simply excludes .retain files when packaging the template while maintaining the directory structure. Since the .retain files can be empty, a simple touch src/main/java/.retain is sufficient.

Add empty .retain files as shown here:

The app/build.gradle file is part of this template project and contains:

The VERSION file is required by the build, because that’s how the build knows what the current version of the template is. Just put any version string into the file:

No quotes. No markup. Just the version text. Note that the build excludes this file from the template zip as the version is included in the zip file’s name.

The DESCRIPTION file is required by the publishing for the description shown during the skeletal list command. Just put a description string into the file:

As with the VERSION file, no quotes or markup, just text.

Finally, README.md contains some information about the template. This is displayed immediately after a new project is created from the template, so it should offer some guidance on what the template provides and what steps to take next with the new project. Add this to the file:

Although the README is not required, you really should include one. It doesn’t have to be Markdown either or have a file extension. We just happen to like the Markdown syntax and the way that GitHub handles files with an md extension.

We didn’t include it here, but we often include a graphical view of the directory structure in the initial README.md created using the tree command. This makes it easy for the user of the template to see where everything is without hunting through the directories.

You can see the full README.md in java-gradle/README.md.

We could simply leave the template as it is, but wouldn’t it be great if the user could set the group ID and version for the project at creation time? That would mean parameterizing the group and version in the build file. Not a problem: we can add a post-install script.

Post-install scripts are executed immediately after a template is unpacked into the new project directory and just before the README is displayed. They are straight Groovy scripts with access to just the core Groovy classes, plus Groovy’s SimpleTemplateEngine and Apache Commons IO (for making file manipulation easier).

Every script has access to the following properties:

The lazybones* properties have been retained for compatability with existing Lazybones templates but now refer to the corresponding Skeletal versions.

The script also has access to all the public and protected methods and properties defined in the LazybonesScript class. Of particular interest are the ask() and processTemplates() methods.

ask() allows the script to request input from a user, such as 'y' or 'n' for whether to include a particular feature or not. Even better, the user can provide the input on the command line, bypassing the input requests all together.

processTemplates() makes it easy to parameterize any of the files in your template using Groovy syntax. It basically runs the source file through Groovy’s SimpleTemplateEngine to produce the resulting file. So if we want to allow the user to specify the project’s group ID and version at install time, we modify build.gradle slightly:

and then add a post-install script, lazybones.groovy, in the root of the template:

The first parameter to ask() is the user prompt message. The second is a default value to use if the user hits enter without providing a value. The third is a property name in the script binding that if provided on the command line will be used instead of prompting the user for one.

To try the template, see installing the template to cache.

Passing parameters to the script binding looks like -P<param>=<value>

From a directory to create the test project in, create the test project:

If you provide them all, you get non-interactive creation of projects from templates.

Since we ran the build file through processTemplates, If you look in your new my-java-app/app/build.gradle you should see group and version updated:

Before continuing cleanup the cache and test project.

Another useful method available to post-install scripts is transformText(). It’s common for scripts to convert strings between camel case (for class names perhaps), lower-case hyphenated (for directory names), and other forms. The transformText() method allows you to do just that:

The from and to arguments are both required and must be one of the NameType enum values: CAMEL_CASE ("MyClass"), PROPERTY ("myClass"), HYPHENATED ("my-class"), or NATURAL ("My Class")

We will use this later in the final script to guess the project class name from the project directory and the project name from that prior to the ask() prompts.

Before we get back to the lazybones.groovy script let’s take care of a directory issue. When we created the project files from gradle init we used a package org.example which added those as org/example subdirectories under src/main/java and src/test/groovy and where the App.java and AppTest.groovy are respectively. We’re going to use the script to create new package directories at creation, so we can remove them from our template by moving the two classes up to src/main/java and src/test/groovy and deleting the org/example directories.

Edit App.java and change the package and class name like shown:

We like to use the Spock naming convention of *Spec instead of *Test, so we will rename AppTest.groovy to AppSpec.groovy and then edit as shown:

Now that the project package and class name are variables, we need to edit build.gradle and use variables for the main class. We will also add settings for the jar archive basename and application name which is the command that gets ran. These would have both defaulted to app since that is the subproject we are working in.

The same for settings.gradle:

Now edit the lazybones.groovy like this:

This is now covered in the Template Testing Companion document. To test, install the template again, create the test project per the instructions, build and run the distribution and then cleanup the cache and test project.

Once the template is ready, it’s time to publish it.

There are three options to use publishing a template, each of which can be accomplished with a simple task provided by the Skeletal Gradle Plugin:

Publishing takes care of the packaging and creates a manifest file in one task. The first time a template is used from a repository it is also added the cache so the install step isn’t required unless you don’t plan on using a remote repository or unless you are doing template development testing.

The relevant Gradle tasks are:

The packaging tasks aren’t often used by themselves, so we’ll skip over those right now. But installing the templates in your local cache is important so that you can easily test them before publication. You can do this on a per-template basis, or simply install all the templates from your templates directory.

If you want to execute a task for a particular template, the <Name> in the above tasks is derived from the name of the template, which comes from the directory name. In our case, the template name is java-gradle. To use this name in the Gradle tasks, we simply camel-case it: JavaGradle. Of course, this means your directories should use hyphenated notation rather than camel-case.

If the rules for converting between camel-case and hyphenated forms don’t suit your template name, for example if you separate numbers with hyphens ('javaee-7'), then you can use hyphens in the task name:

Once you’re happy with the template, you can publish it for a simple URL repository. To do that, you have to configure the build. If you have a look at my-lzb-templates/build.gradle, you’ll see this section:

templateOwner is used in the manifest file as the template owner or creator. This owner is used for all templates published from this lazybones project.

To publish the template and create the manifest file:

This will create the zip archive and a skeletal-manifest.txt file. This manifest is a simple CSV formatted text file with an entry for each template published.

See the Skeletal Gradle Plugin for instructions on applying the plugin to your Gradle build, task usage, and advanced configuration.

The packaging process is by default rather dumb. It will include all files and directories in the target template directory except for a few hard-coded exceptions (the DESCRIPTION, VERSION, and .retain files for example). That leaves a lot of scope for accidentally including temporary files in the package! To help you avoid that, the plugin allows you to specify a set of extra exclusions using Apache Ant-style patterns.

These exclusions apply to all templates. If you want template-specific exclusions, then use the following syntax:

Note that the template-specific settings completely override the global ones, so if you want the global ones to apply you will need to repeat them in the template-specific list.

Another potential issue when packaging templates is with file and directory permissions. Lazybones attempts to retain the permissions it finds in the template directory, but these may not be correct on Windows. To compensate for that, the plugin allows you to specify file permissions in the template configuration:

The first argument is the Unix-style permission as a string (such as "600", "755" and so on), and the rest are a list of Ant-style patterns representing the files and directories that the permission string should apply to. You can have multiple fileMode() entries, although ideally you should only have one per file mode.

As with package exclusions, you can also specify file modes on a per-template basis:

Again, the template-specific settings replace the global ones for that particular template.

That’s it for the getting started guide. You’ve created a template, tested it, and finally published it for a URL repository. For the rest of the guide we’ll look at the template creation in more detail.