Drupal 8 - rendre un formulaire dans un template

La form api de drupal est très puissante, mais pour jouer avec le markup html avec les #prefix et #suffix peut s'avérer rapidement complexe en plus d'être un peu sale au niveau du code.

Dans drupal 8 il est possible de facilement utiliser un template pour un formulaire. Pour cela il faut se baser sur le nom machine du formulaire.

Cela fonctionne pour nos formulaires custom, mais aussi pour les formulaires des modules tiers ou du core. Je vais ici utiliser un template pour le formulaire user_form qui correspond au formulaire de modification du compte utilisateur. Le nom machine de ce formulaire est user_form.

Définition du template :

Fichier : mon_module.module

function mon_module_theme() {
  $theme = [];
  $theme['user_form'] = [
    'render element' => 'form',
    'template' => 'user-form',
  ];
  return $theme;
}

J'utilise comme clé de thème le nom machine du formulaire.

Je peux ensuite créer dans le dossier templates de mon thème le fichier user-form.html.twig : (attention au _ remplacé par un -)

<div>
  <p>Test</p>
  {{ form }}
<div>

On peut rendre des champs « manuellement », mais il ne faut pas oublier de rendre le formulaire form à la fin : 

<div>
  {{ form.form_build_id }}
  {{ form.form_token }}
  {{ form.form_id }}
  <p>Test</p>
  <div class="col-sm-6">
    {{ form.mon_champ_1 }}
  </div>
  <div class="col-sm-6">
    {{ form.mon_champ_2 }}
  </div>
  {{ form | without('mon_champ_1', 'mon_champ_2') }}
<div>

Note, il est aussi possible de spécifier un template autre dans un form alter par exemple :

function MON_MODULE_form_views_exposed_form_alter(&$form, &$form_state) {
  if ($form['#id'] === 'views-exposed-form-recherche-page') {
    $form['#theme'] = 'form_recherche_block';
  }
}