Hooks Declarativos

O que são Hooks Declarativos?

Os Hooks Declarativos são uma forma de definir ações a serem executadas em momentos específicos da aplicação de um Template ou Plugin.

A aplicação de um Template ou Plugin possui duas fases distintas:

Fase 1. Perguntar ao usuário os parâmetros de entrada.
Fase 2. Interpolar os templates Jinja usando os valores informados para geração de arquivos.

Você pode executar as ações definidas nos Hooks Declarativos:

• Antes de inserir os parâmetros de entrada (before-input)
• Antes de interpolar os templates Jinja para a geração dos arquivos (before-render)
• Depois de gerar os arquivos (after-render)

Para entender melhor as fases de aplicação dos Templates e Plugins, confira o Ciclo de renderização de Templates e Plugins

Como definir os Hooks Declarativos?

A definição dos Hooks Declarativos de um Template ou Plugin podem ser feitas no arquivo de configuração template.yaml e plugin.yaml, conforme o exemplo abaixo:

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

É possível definir vários hooks em um mesmo Template ou Plugin.

Gatilhos

Os gatilhos dos Hooks Declarativos são definidos pelo atributo trigger e indicam em que momento o Hook Declarativo irá executar, podendo assumir um dos seguintes valores:

• before-input: Antes de perguntar os parâmetros para o usuário.
• before-render: Antes de gerar os arquivos.
• after-render: Após gerar os arquivos.

Condições

A execução de um Hook Declarativo pode ser condicional e é controlada pelo atributo opcional condition. Você deve definir uma condição com:

1. Uma variável (variable);

2. Um operador (operator);

3. Em seguida, o valor de referência (value).

As variáveis acessíveis são as definidas pelos inputs computed-inputs do Template/Plugin. No trecho de exemplo apresentado abaixo, é verificado se o valor do input language é igual à string java. Em caso positivo, são gerados os arquivos definidos pelos Templates que estão na pasta templates-java.

hooks:
  - type: render-templates
    trigger: after-render
    path: templates-java
    condition:
      variable: language
      operator: "=="
      value: java

Os operadores disponíveis para condições são:

• "==": Valida se os valores são iguais.
• "!=": Valida se os valores são diferentes.
• ">": Valida se a variável é maior ao valor.
• "<": Valida se a variável é menor ao valor.
• ">=": Valida se a variável é maior ou igual ao valor.
• "<=": Valida se a variável é menor ou igual ao valor.
• containsAny: Valida se a variável do tipo lista contém qualquer um dos valores contidos em value.
• containsAll: Valida se a variável do tipo lista contém todos os valores valores contidos em value.
• containsOnly: Valida se a variável do tipo lista contém todos os valores valores contidos em value e não contém outros elementos.

Confira os tipos de Hooks Declarativos abaixo:

Tipos de Hooks	O que fazem
run	Executam alguns comandos.
run-script	Executam scripts Python, dentro de um arquivo plugin.yaml ou template.taml.
edit	Definem alterações feitas em arquivos existentes.
edit-xml	Definem alterações feitas em arquivos XML existentes.
edit-json	Definem alterações feitas em arquivos JSON existentes.
edit-yaml	Definem alterações feitas em arquivos YAML existentes.
render-templates	Executam a geração condicional de arquivos.