Hooks Declarativos

Defina ações para serem executadas em momentos específicos da aplicação de um Template ou Plugin ao criar o seu projeto.

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

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 e 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:


Hooks Declarativos

Nesta seção, você encontra detalhes sobre os Hooks Declarativos.

run

Nesta seção, você encontra a referência de um Hook Declarativo do tipo run.

run-script

Nesta seção, você encontra a referência de um Hook Declarativo do tipo run-script.

edit

Nesta seção, você encontra a referência de um Hook Declarativo do tipo edit.

edit-xml

Nesta seção, você encontra a referência de um Hook Declarativo do tipo edit-xml.

edit-json

Nesta seção, você encontra a referência de um Hook Declarativo do tipo edit-json.

edit-yaml

Nesta seção, você encontra a referência de um Hook Declarativo do tipo edit-yaml.

render-templates

Nesta seção, você encontra a referência de um hook declarativo do tipo render-templates.