Skip to content

Instantly share code, notes, and snippets.

@Kerruba
Last active August 28, 2020 15:07
Show Gist options
  • Save Kerruba/f0976ccd000d0454b10e52fe412d09ba to your computer and use it in GitHub Desktop.
Save Kerruba/f0976ccd000d0454b10e52fe412d09ba to your computer and use it in GitHub Desktop.
Documentation about JHipster files template

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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment