Documentation about JHipster files template

jhipster_file_template_docs.md

JHipster file templates documentation

Here some documentation I created to better understand the content of the files.js in JHipster generators

File template overview

This is an example of a file object. Each file object has:

• condition: is a function of the generator that is used to check if the file(s) has to be created
• path: is the base path where the file has to be found from the generator
• template: could either be a string or an object. Usually it's a string, and this implies that the path reference an ejs template and the method to use is template.

You can further configure the template by using an object instead of a string. Here is an example of a file template that uses an object for the template field:

//This is a file template
{
    "name": [
    {
        condition: generator => generator.databaseType === 'sql',
        path: SERVER_MAIN_RES_DIR,
        templates: [
        {
            file: 'config/liquibase/changelog/added_entity.xml',
            method: 'copy',
            useTemplate: false,
            options: {},
            noEjs: true,
            renameTo: generator => `config/liquibase/changelog/${generator.changelogDate}_added_entity_${generator.entityClass}.xml`,
            override: false
        }]
	}]
}

File template configuration fields

In the next table I'll list the main fields of the template object. Note that I'll call from-file the source file (the file to use from the templates in the generator) and dest-file the destination file (where the file has to be put in the final project)

field	type	default	description
file	[Function, String]		Defines where to look for the from-file relative to the path. It's assumed that the file is an ejs file, if is not you need to set the noEjs field to true
method	[String]	template	Defines the method to use when generating the dest-file, could be template, copy
useTemplate	[Any]	false	Defines the contex parameter passed to ejs
options	[Object]	{}	Contains the options to send to ejs
noEjs	[Boolean]	false	Tells if the file is an ejs file or a regular file
renameTo	[Function]		Is a function that accept the generator as parameter and allow to customize the dest-file name and path
override	[Boolean]	undefined	tells if the file has to override an existing file or not

The writeFiles function

These file templates are usually sent to the writeFiles function in this format:

let files = [...] // the list of file templates
let generator = this;
let returnFiles = false; // Return the list of files generated whitout writing them on disk
let prefix = ``; // A prefix that will be added to the destination file

this.writeFiles(files, generator, returnFiles, prefix);

We will later see how the prefix is used when calculating the dest-file.

How from-file and dest-file are calculated

from-file

• If the template field is a string, the from-file is path + template
• If template is an object and template.file is a string, the from-file is going to be path + ${template.file}
• If template is an object and template.file is a function, the from-file will be path + ${template.file(generator)} (Note: the template.file function should take the generator as paramenter in order to work correctly)

If to the writeFiles function a prefix is passed (last parameter), that's added at the end to generate the templatePathFrom

let templatePath = ... // See above possibilities: path + [template | filename | file(generator)];
let from-file = prefix ? `${prefix}/${templatePath} : templatePath;

dest-file:

• If template is a string, the .ejs is removed from the from-file and this becomes the dest-file
• If template is an object and has a renameTo function, the dest-file becomes path + renameTo(generator)