Home
Guides
Sign in

Customizing service generator templates

Suggest Edits

When creating micro-service API's  in the CLI,  the ol generate command uses templates to render the source code files of the generated service. The templates are written in the FreeMarker Template Language (FTL) and contain the boilerplate source code of the generated service. The ol generate command uses the Apache FreeMarker™ template engine to process the templates and render the service source code.

In addition to the prepackaged template set of the ol generate command, you can create custom templates or edit existing ones. 

Step 1. Copy template name

To edit an existing template or create a new template based on an existing template, you need to have at your disposal the template name. To view the list of templates available to you, run the ol list templates command. The template list consists of templates included in the generator plugins you installed and custom templates you already created. 

> ol list templates

$ ol list templates

The template list is displayed.

name                                    status                                 
================================================================================
 my_awsome_template.ftl                  CUSTOM
 api-ol-config.yml.ftl                   DEFAULT                                
 gradle.properties.ftl                   MODIFIED 
 build.gradle.kts.ftl                    DEFAULT                                
 buildSrc.build.gradle.kts.ftl           DEFAULT                                
 editorconfig.ftl                        DEFAULT                                
 git-ignore.ftl                          DEFAULT                                                      
 java-entity.ftl                         DEFAULT                                
 java-enum.ftl                           DEFAULT                                
 java-field-utils.ftl                    DEFAULT                                
 java-operation.ftl                      DEFAULT

Each template in the list can have one of the following statuses.

  • DEFAULT: A template included in one of the generators installed locally in CLI in its original form without customizations.
  • DRAFT: A template that you already copied for editing by executing the ol templates edit command but did not yet apply any edits to.
  • MODIFIED: A template you copied for editing by executing the ol templates edit command, then edited and then applied the edits by saving. 
  • CUSTOM: A template you created by executing the ol create template command.
  1. Copy the name of the template you want to edit.

Step 2. Edit an existing template

Run the ol templates edit command to edit templates prepackaged with the generator plugins installed on your local CLI tool. 

  1. Run the ol templates edit with the name of the template you want to edit as an argument. 
    temp> ol templates edit java-spring-main-class.ftl

    temp$ ol templates edit java-spring-main-class.ftl

❗️

The template you selected is created in /Users/[username]/.ol/cli/templates/

  1. Open the newly created template copy in a code editor, apply your changes and save your files.

    ❗️

    The original template is removed from the template list.

Step 3. Create a template

In contrast to modifying an existing template, you can create a new custom template altogether. The new template either overrides an existing template in the prepackaged generator template set or is added alongside it. 

When you create a template, specify the new template's name, the file that will serve as the initial source of the new template, the name of the file generated from the template, and its location in the generated service folder.

  1. Run the ol create template command with the name of the template you want to create, the file that will serve as the initial source of the new template, the name of the file generated from the template, and its location in the generated service folder. 
    > ol create template --name test_template.ftl --source d: \tmp\text.ftl --target-path text2.txt -f

    $ ol create template --name test_template.ftl --source d: \tmp\text.ftl --target-path text2.txt -f

The command will perform the following:

  • The file test_template.ftl is added to your local templates folder at .ol/cli/templates.
  • The new template is registered in templates.config located at .ol/cli/templates.

  1. Open the newly created template copy in a code editor, apply your changes and save your files.

    After you generate a service with the ol generate command, the FTL engine will process the template and generate text.txt in the root of the service folder.

    ❗️

    If the value of the --name option has an extension other than *.ftl, the generated file will not be processed by the FTL engine. In that case, the file specified as the value of the --source option will only be copied to the generated service folder.

Step 4. Edit the template

  1. Go to .ol/cli/templates and open the newly created template copy in a code editor.
    The template file begins with the generic comment: 
    <#-- @ftlvariable name="genericModel" type="io.openlegacy.cli.models.GenericTemplateModel" -->
  2. Add your content to the template. For example, you can add an FTL variable such as $(genericModel.projectName) and a literal string such as "Project Name: ". 
    <#-- @ftlvariable name="genericModel" type="io.openlegacy.cli.models.GenericTemplateModel" -->
Project Name: ${genericModel.projectName}
  3. You can also add dynamic variables that accept their values from an ol generate command option value. 
    <#-- @ftlvariable name="genericModel" type="io.openlegacy.cli.models.GenericTemplateModel" -->
Project Name: ${genericModel.projectName}
Custom Value: ${genericModel.properties.customValue}

Step 5. Review the generated file

After you updated a template file or created a new one you can generate the service and review the source code file rendered from your template file:

  1. Run ol generate to generate a service based on one of your projects and generators. Use the --model option to insert a value to the customValue option. 
    > ol generate --project demo-account-details --generator spring-java-rest --model customValue=some_value

    ol generate --project demo-account-details --generator spring-java-rest --model customValue=some_value
  2. Go to the generated service folder and navigate to the location of the rendered source code file. In our example, the location is the generated service root folder, and the rendered file name is text2.txt.
  3. Open file text2.txt. The content should be: 
    Custom Value: some_value
Project Name: demo-accout-details

Updated 4 months ago