Template definition

Template definition is YAML file located in /.scf/template.yaml directory of template git repository. It contains template configuration, namely:

template version - defines version of the template definition file
template files matchers - identifies all temlate files inside your template git repository using Ant matching pattern
directory expansions - describes how template directory will be expanded during template execution (e.g. to _package_ template directory will be replaced with org/mycompany/myproject directory)
required templates - specifies on which other templates current template depends on
variables - defines template variables, which are used in template files, their types and other parameters. Scaffander will use this information to render input form for the user to gather variable values prior to template execution

All sections and even template file itself are optional.

Template definition example

This is sample template.yaml file and its rendered output. All the file blocks will be explained in detail in next sections.

Template definition

version: 1.0 
templates: # consider all java files and pom.xml file as template
  - "**/*.java"
  - pom.xml
directoryExpansion: # expand directory _package_ according to package variable value
  - name: _package_
    value: ${package?replace(".", "/")}
requires: # this template depends on maven wrapper template
  - urn:scf:job:cloud:default:maven-wrapper
variables: # all variables of the template
  - id: springBootVersion
    name: SpringBoot version
    type: choice
    required: true
    options:
      - name: "2.5.0 (SNAPSHOT)"
        value: "2.5.0.BUILD-SNAPSHOT"
      - name: "2.4.6 (SNAPSHOT)"
        value: "2.4.6.BUILD-SNAPSHOT"
      - name: "2.3.11 (SNAPSHOT)"
        value: "2.3.11.BUILD-SNAPSHOT"
      - name: "2.5.0 (RC1)"
        value: "2.5.0.RC1"
      - name: "2.4.5"
        value: "2.4.5"
      - name: "2.3.10"
        value: "2.3.10"
  - id: name
    name: Name
    type: string
  - id: description
    name: Description
    type: string
  - id: packaging
    name: Packaging
    type: choice
    required: true
    options:
      - name: JAR
        value: jar
      - name: WAR
        value: war
  - id: java-version
    name: Java version
    type: choice
    required: true
    options:
      - name: 17
        value: 17
      - name: 11
        value: 11
      - name: 8
        value: 8
  - id: dependencies
    name: Dependencies
    type: list
    items:
      - id: lombok
        name: Lombok
        description: Java annotation library which helps to reduce boilerplate code.
        group: Developer tools
        data:
          group-id: org.projectlombok
          artifact-id: lombok
      - id: springboot-devtools
        name: Spring Boot DevTools
        description: Provides fast application restarts, LiveReload, and configurations for enhanced development experience.
        group: Developer tools
        data:
          group-id: org.springframework.boot
          artifact-id: spring-boot-devtools
      - id: springboot-configuration-processor
        name: Spring Configuration Processor
        description: 'Generate metadata for developers to offer contextual help and "code completion" when working with custom configuration keys (ex.application.properties/.yml files).'
        group: Developer tools
        data:
          group-id: org.springframework.boot
          artifact-id: spring-boot-devtools

Given template definition will render following generator input form in Scaffander:

Spring project example

Spring project with values

`version` block

Specifies version of template definition file. Only version 1.0 is currently supported. Parameter type is string.

Template definition

version: 1.0

`templates` block

templates block is list of Ant matching patterns which identifies all template files inside template directory structure starting from template root directory. Parameter type is list of strings.

The mapping matches files using the following rules:

? matches one character
* matches zero or more characters
** matches zero or more directories in a path

Ant patern examples:

src/t?st.java - matches src/test.java but also com/tast.java or com/txst.java
source/*.php - matches all .php files in the source directory
source/**/test.rb - matches all test.rb files underneath the source path
ace/rimmer/**/*.jsp - matches all .jsp files underneath the ace/rimmer path
rick/**/gets/schwifty.jsp - matches rick/gets/schwifty.jsp but also rick/only/gets/schwifty.jsp and rick/and/morty/gets/schwifty.jsp

As an example, you can specify the templates like this:

Template definition

templates:
  - "**/*.java" # include all java files
  - "resources/**/*.xml" # include all xml files inside resource directory

`directoryExpansion` block

This block defines which template directories to expand and how. Directory expansion is a process when given directory is transformed into specified directory path, for example template_directory is transformed to org/mycompany/subfolder/anothersubfolder during project generation. Directory expansion is the only block, which can reference variables from variables block and therefore we can do something like this:

Template definition

directoryExpansion:
  - name: _package_
    value: ${package?replace(".", "/")}

Here you have told Scaffander to use value of package variable and replace all occurences of . character in it with / (directory separator). Then Scaffander looks for all directories named _package_ and expands them according to the resolved value. Let’s assume we have template directory src/main/java/_package_ and package variable is set to org.quarkus.service, then output directory will be src/main/java/org/quarkus/service.

Type of directoryExpansion block is list of name/value pairs, both name and value are of string type.

`requires` block

Requires block defines list of templates on which current template depends. You can even reuse variables from referenced templates in the current template files. The syntax is following ([] marks optional blocks):

Template definition

requires:
  - urn_identifier1 [AS name] [| another_urn_identifier [AS name2]]
  - ...

Example 1

For example, this way you can express that current template depends on maven and readme-md templates:

Template definition

requires:
  - urn:scf:job:cloud:workspace:maven 
  - urn:scf:job:cloud:workspace:readme-md

Example 2

This template depends on maven template, but I want also reference Maven variables in template files as $maven.*. (e.g. ${$maven.version} expression will be replaced with selected Maven version in template files):

Template definition

requires:
  - urn:scf:job:cloud:workspace:maven AS maven

Example 3

You can tell Scaffander that your template requires at least one of the templates, either maven or gradle using pipe |. Their variables will be referenced as $maven.* and gradle.* in the template files as specified below:

Template definition

requires:
  - urn:scf:job:dev-local:foo:maven-wrapper AS maven | urn:scf:job:dev-local:foo:gradle-wrapper AS gradle

In this case Scaffander displays selection dialog when you try to add current template into generator to choose the dependency template.

Template dependecies

Example 4

You can even use the same name for dependency template, which means variables of gradle and maven will be merged into single object buildSystem. This is useful in rare cases when both gradle and maven share same variables, so expression (e. g. ${$buildSystem.version} will be evaluated as Gradle version when you choose Gradle as build system or Maven version, when you choose Maven:

Template definition

requires:
  - urn:scf:job:dev-local:foo:maven-wrapper AS buildSystem | urn:scf:job:dev-local:foo:gradle-wrapper AS buildSystem

`variables` block

Variables block defines list of variables to be used in template files. Scaffander will generate input form, to gather variable values from the user prior to code generation.

`string` variable

Basic input variable, which renders input field for one-line string.

Property	Type	Required	Description
`id`	string	yes	unique identifier of the variable, variable is referenced in template files by its `id`
`name`	string	yes	name of the variable, which will be rendered in template input form
`type`	string	yes	use `string` constant
`required`	boolean	no (default `false`)	set to `true`, when value is mandatory
`pattern`	string	no (empty by default)	regular expression to validate input value

Example with validation pattern:

Template definition

variables:
  - id: package
    name: Package
    type: string
    required: true
    pattern: '^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+[0-9a-z_]$'

Rendered input component and validation example:

String variable

String variable with validation error

`text` variable

Basic input variable, which renders textarea field for multi-line string.

Property	Type	Required	Description
`id`	string	yes	unique identifier of the variable, variable is referenced in template files by its `id`
`name`	string	yes	name of the variable, which will be rendered in template input form
`type`	string	yes	use `string` constant
`required`	boolean	no (default `false`)	set to `true`, when value is mandatory

Example:

Template definition

variables:
  - id: description
    name: Description
    type: text

Rendered input component with sample data:

Text variable

`choice` variable

Select variable renders group of radion buttons, which allows the user to select one of the values. If the number of options is higher, you can prefer select variable which renders drop-down list.

Property	Type	Required	Description
`id`	string	yes	unique identifier of the variable, variable is referenced in template files by its `id`
`name`	string	yes	name of the variable, which will be rendered in template input form
`type`	string	yes	use `choice` constant
`required`	boolean	no (default `false`)	set to `true`, when value is mandatory
`options`	`choiceOption[]` (choice option list)	no (list is empty by default)	list of name value pairs (see table below)

choiceOption type:

Property	Type	Required	Description
`name`	string	no (`value` is used if not specified)	option display name
`value`	string	yes	value of the option

Example usage:

Template definition

variables:
  - id: springBootVersion
    name: SpringBoot version
    type: choice
    required: true
    options:
      - name: "2.5.0 (SNAPSHOT)"
        value: "2.5.0.BUILD-SNAPSHOT"
      - name: "2.4.6 (SNAPSHOT)"
        value: "2.4.6.BUILD-SNAPSHOT"
      - name: "2.3.11 (SNAPSHOT)"
        value: "2.3.11.BUILD-SNAPSHOT"
      - name: "2.5.0 (RC1)"
        value: "2.5.0.RC1"
      - name: "2.4.5"
        value: "2.4.5"
      - name: "2.3.10"
        value: "2.3.10"

Select variable

`select` variable

select variable renders dropdown list, which allows the user to select one of the values. It is similar to choice variable which renders group of radio buttons, but select should be preferred when number of items is higher.

Property	Type	Required	Description
`id`	string	yes	unique identifier of the variable, variable is referenced in template files by its `id`
`name`	string	yes	name of the variable, which will be rendered in template input form
`type`	string	yes	use `select` constant
`required`	boolean	no (default `false`)	set to `true`, when value is mandatory
`options`	`selectOption[]` (select option list)	no (list is empty by default)	list of name value pairs (see table below)

selectOption type:

Property	Type	Required	Description
`name`	string	no (`value` is used if not specified)	option display name
`value`	string	yes	value of the option

Example usage:

Template definition

variables:
  - id: version
    name: Maven version
    type: select
    required: true
    options:
      - name: Latest # value 3.8.4 is displayed as Latest
        value: 3.8.4
      - value: 3.8.4 # and also as 3.8.4
      - value: 3.8.3
      - value: 3.8.2
      - value: 3.8.1
      - value: 3.6.3
      ...

Scaffander renders this input:

Select variable

`list` variable

List variable allows user to select from multiple options (useful for listing dependecies, extensions etc. for the project). Scaffander renders selection dialog with search capabilities and item categorization to make the selection as easy as possible.

Property	Type	Required	Description
`id`	string	yes	unique identifier of the variable, variable is referenced in template files by its `id`
`name`	string	yes	name of the variable, which will be rendered in template input form
`type`	string	yes	use `list` constant
`required`	boolean	no (default `false`)	set to `true`, when value is mandatory
`items`	`listItem[]` (list of items)	no (list is empty by default)	list of listItems (see below)

listItem type:

Property	Type	Required	Description
`id`	string	yes	unique identifier of the item
`name`	string	yes	display name of the item
`description`	no	yes	description of the item displayed in selection dialog
`group`	string	no	Specifies both group name and the group identifier. All items within the same group will be displayed under same category in selection dialog
`data`	object	yes	key value pairs, which holds the data of current item, both key and value have string type

Example usage:

Template definition

variables:
  - id: extensions
    name: Extensions
    type: list
    items:
      - id: quarkus-config-yaml
        name: YAML Configuration
        description: Use YAML to configure your Quarkus application
        group: Core
        data:
          group-id: io.quarkus
          artifact-id: quarkus-config-yaml
      - id: quarkus-logging-json
        name: Logging JSON
        description: Add JSON formatter for console logging
        group: Core
        data:
          group-id: io.quarkus
          artifact-id: quarkus-logging-json
      - id: quarkus-consul-config
        name: Consul Config
        description: Read runtime configuration from Consul Key - Value store
        group: Core
        data:
          group-id: io.quarkus
          artifact-id: quarkus-consul-config
      - id: quarkus-logging-gelf
        name: Logging GELF
        description: Log using the Graylog Extended Log Format
        group: Core
        data:
          group-id: io.quarkus
          artifact-id: quarkus-logging-gelf
      - ...

Rendered input (empty selection):

List variable - empty

Selection dialog (opened by clicking on Add… button):

List variable - selection dialog

Selected values:

List variable - selection

Scaffander chevron_right

Generators

Templates

Managed repositories

Template language chevron_right

Overview

Template files

Further topics

Reference

Template definition