Skip to main content
Version: v4.4.0

Declarative Hooks

What are Declarative Hooks?

Declarative Hooks is a way to define actions you can perform at a specific time while applying a Template or a Plugin.

The application of a Template or Plugin has two different phases:

Phase 1. Ask the user for input parameters.
Phase 2. Interpolate Jinja's templates using the entered values to generate a file.

You can perform the actions defined in the Declarative Hooks:

  • Before input parameters (before-input)
  • Before interpolating Jinja's templates to generate the files (before-render)
  • After generating the files (after-render)

To better understand the stages to apply Templates and Plugins, check the Templates-and-Plugins Rendering Cycle page.

How to define Declarative Hooks?

Declarative Hooks definitions for a Template or Plugin can be done in the configuration file template.yaml and plugin.yaml, as in the example below:

hooks:
- type: run
trigger: before-input
working-dir: "{{project_name}}"
commands:
- echo plugin-python before-input!
- type: run-script
trigger: before-render
script: script.py
- type: edit
trigger: after-render
path: src/some-file.txt
changes:
- insert:
line: 0
value: "# Text inserted in first line\n\n"
when:
not-exists: "# Text inserted in first line"
- search:
string: "# Text inserted in first line"
insert-before:
snippet: snippets/insert-before-first-line.txt
when:
not-exists: "# Text inserted before first line"
- search:
pattern: (Text )inserted in( first line)
replace-by:
value: \1moved from\2
when:
not-exists: print(f"Hello {name}!")
- type: render-templates
trigger: after-render
path: templates-java
condition:
variable: language
operator: "=="
value: java
info

It is possible to define multiple Hooks in the same Template or Plugin.

Triggers

Declarative Hooks triggers are defined by the trigger attribute and indicate when Declarative Hook will execute. It can take one of the following values:

  • before-input: Before asking the user for parameters.
  • before-render: Before generating the files.
  • after-render: After generating the files.

Conditions

Declarative Hook execution can be conditional and is controlled by the optional condition attribute. You must define a condition with:

1. A variable (variable);

2. An operator (operator);

3. Then, the reference value (value).

The accessible variables are defined by the inputs and computed-inputs of a Template/Plugin.

The code snippet below verifies if the value of the language input is equal to the java string. If so, the files defined by the Templates in the templates-java folder, are generated.

hooks:
- type: render-templates
trigger: after-render
path: templates-java
condition:
variable: language
operator: "=="
value: java
  • "==": Validates if the values are equal.
  • `"!=": Validates if the values are different.
  • ">": Validates if the variable is greater than the value.
  • "<": Validates if the variable is less than the value.
  • ">=": Validates if the variable is greater than or equal to the value.
  • "<=": Validates if the variable is less than or equal to the value.
  • containsAny: Checks if the list variable contains any of the values in value.
  • containsAll: Validates if the list variable contains all the values in value.
  • containsOnly: Validates if the list variable type contains all the values in value and has no other elements.
  • containsAll: Validates if the list variable contains all the values contained in value.
  • containsOnly: Validates if the variable of type list contains all the values contained in value and contains no other elements.

See the Declarative Hooks types below:

Hook typesWhat they do
runIt runs commands.
run-scriptIt runs Python scripts, in a plugin.yaml or template.taml file
editIt defines changes made to existing files
edit-xmlIt defines changes made to existing XML files.
edit-jasonIt defines changes made to existing JSON files.
edit-yamlIt defines changes made to existing YAML files.
render-templatesIt can be used to perform the conditional generation of files.

Was this page helpful?