Custom templates

[daxartio]

Description

I think it would be a good idea if we could use our own templates instead of ones like this

loco/src/gen/scaffold.rs

Line 12 in e544fa4

const HTMX_VIEW_EDIT_SCAFFOLD_T: &str = include_str!("templates/scaffold/htmx/view_edit.t");

Expected Behavior

Developers can configure their own templates in their applications. By default, it will work as it does now.

[kaplanelad]

Hey @daxartio,

Thanks for the suggestion, it sounds like a great idea!

To be clear, how would you envision editing the templates? For example, with the scaffold, multiple templates are involved. Would you expect to customize just one template, or would you need to modify all of them?

How would you expect the CLI flags to behave when specifying custom templates?

[daxartio]

I expect this behavior to work like this.
Developers have their own templates in their repositories or in different directories on their local machines.
There is a global config, or a local one for a specific project, that includes the path to the templates. They can also pass an argument through the CLI.
When they generate something, loco-rs uses the developer's templates.
We can also create custom starters, following the same idea.

I think a single template configuration should be enough. The priority of configurations is as follows: CLI argument -> local -> global. I’m not entirely sure about the local and global configurations; maybe they will work through environment variables or a configuration file.

Most likely, users will provide the same files and structure as in the loco-rs repository, and if certain files are missing, loco-rs will use the default templates.

[jondot]

#1052 creates a clear folder structure that we can later "overlay" a custom folder structure on

[jondot]

@daxartio my thoughts are these, highlighting the freedoms/limitations

1. we will start with a .loco-templates folder (other options: .templates, _templates, .loco-gen (so that its specific), local to the project (as opposed to global). Reasoning: (1) once a project is compiled this material is not needed (2) each project may have a different loco version and templates may be version specific (3) it is easy to whole-sale copy this folder or symlink, or use a git submodule for it. there may be an easy-to-build "bubble up" hierarchy lookup. meaning you can place ~/.loco-gen overriding some files, and also local .loco-gen overriding other files, and the total overriden files will be a union of all. In such case we have to indicate the overlay layers for debugging purposes, and show what files are overriden where.
2. the folder structure will be overlay based. Meaning, if I replicate the folder structure and place just a single file deployments/docker/ignore.t only this file will be user-specific and the rest will come from the framework.
3. As with all implicit actions we have to guardrail the user. we need (a) a way to "eject" or place default templates into custom folder, based on user request (b) highlight and indicate clearly to the user that a custom template was used.

suggestions

3.a) cargo loco g --eject deployment docker
creates the folder layout (mkdir -p semantics), and places all relevant files for this generator, copied from within Loco.

name for the flag:

• --eject (cargo cult from create-react-app)
• --copy-template (verbose, clear)
• --custom (indicating custom templates)
• --edit/--customize (indicating the intent, the user wants to edit this generator, so just happens that we use custom templates)

3.b) ways to make sure a user knows a custom template is used:

• on first time use, show a prompt indicating this is happening (save a magic file to never ask again)
• display a banner after injection finished saying a custom template was used and its location
• add a comment to the generated file indicating a custom template was used and what template was used (may be good to do anyway)

[daxartio]

Many thanks