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.

See the Declarative Hooks types below:

Hook types	What they do
run	It runs commands.
run-script	It runs Python scripts, in a plugin.yaml or template.taml file
edit	It defines changes made to existing files
edit-xml	It defines changes made to existing XML files.
edit-json	It defines changes made to existing JSON files.
edit-yaml	It defines changes made to existing YAML files.
render-templates	It can be used to perform the conditional generation of files.