Template developers guide

Lazybones alone is just a tool that doesn't do much. It needs a solid selection of template packages to make it a compelling solution for developers' day-to-day needs. That's why we try to make it as easy as possible to develop and publish templates. This guide explains how to go about both steps.

Anatomy of a template

TODO Complete this, using whatever is useful from the text below the separator

--

If you have an idea for a project template and want to add it to lazybone's library, then you have two options:

1. Fork this repo, add your template source to src/templates and submit a pull request
2. Keep the source in your own repository, build a zip package for the template, publish it to Bintray and finally send a link request to the pledbrook/lazybones-templates repository

The second option, a binary contribution, is currently the preferred one. Otherwise the source for this project could grow too large. Plus it's good for contributors to take responsibility for publishing their own binaries.

Requirements for a project template:

• Must have a VERSION file in the root directory containing just the current version number of the template
• A README, README.txt, README.md (or any README.* file) in the root of the project. This file will be displayed straight after a new project is created from the template, so it should give some information about what the template contains and how to use it
• An optional lazybones.groovy post install script in the root of the template directory (see below for more details). It runs right after the template is installed and is deleted after successful completion.
• The name of the binary must be of the form <name>-template-<version>.zip and should not contain a parent directory. So a README file must be at the top level of the zip.
• The name of the template should ideally be of the form <tool/framework>-<variant>, where the variant is optional. For example: ratpack-lite, dropwizard, grails-cqrs.

The lazybones.groovy post install script is a generic groovy script with a few extra helper methods:

• ask(String message, defaultValue = null) - asks the user a question and returns their answer, or defaultValue if no answer is provided

• ask(String message, String propertyName, defaultValue = null) - works similarily to the ask above, but allows grabbing variables from the command line as well based on the propertyName.

• filterFiles(String filePattern, Map substitutionVariables) - use ant pattern matching to find files and filter their contents in place using Groovy's SimpleTemplateEngine.

• hasFeature(String featureName) - checks if the script has access to a feature, hasFeature("ask") or hasFeature("fileFilter") would both return true

Here is a very simple example lazybones.groovy script that asks the user for a couple of values and uses those to populate parameters in the template's build file:

def params = [:]
params["groupId"] = ask("What is the group ID for this project?")
params["version"] = ask("What is the project's initial version?", "version", "0.1")

filterFiles("*.gradle", params)
filterFiles("pom.xml", params)

The main Gradle build file might then look like this:

apply plugin: "groovy"

<% if (group) { %>group = "${group}"<% } %>
version = "${version}"

The ${} expressions are executed as Groovy expressions and they have access to any variables in the parameter map passed to filterFiles(). Scriptlets, i.e. code inside <% %> delimiters, allow for more complex logic.