Aller au contenu

Form theme du design-system

Référence du thème de formulaire Twig de Kirexo : le fichier templates/form/kirexo_theme.html.twig, son enregistrement global, et le mapping exact des blocs de widgets Symfony vers les composants du design system. Ce thème permet à tout form_widget() de rendre un markup stylé DS sans coller de classe à la main sur chaque champ.

Rôle et principe

Sans thème de formulaire, les form_widget() retombent sur le thème Symfony par défaut (form_div_layout.html.twig) et produisent des <input> / <select> / <textarea> bruts, sans les classes du DS — donc non stylés. Le thème Kirexo résout ce problème globalement : tout formulaire rendu via les fonctions Twig (form_row, form_widget, form_errors…) reçoit automatiquement les classes du design system.

Le thème suit deux principes :

  • Fusion, pas réécriture. Chaque bloc surchargé fusionne une classe DS dans attr.class puis délègue à parent(). Le <input> / <select> complet n'est jamais réécrit, ce qui rend le thème robuste aux montées de version de Symfony.
  • Aucune couleur. Le thème n'introduit ni hexadécimal ni style="". Les couleurs proviennent exclusivement des classes DS, conformément à la contrainte couleur du projet.

Enregistrement global

Le thème est enregistré pour tous les formulaires de l'application via la clé form_themes dans config/packages/twig.yaml :

twig:
    default_path: '%kernel.project_dir%/templates'
    file_name_pattern: '*.twig'
    form_themes:
        - 'form/kirexo_theme.html.twig'

Le chemin est relatif à default_path (templates/), d'où 'form/kirexo_theme.html.twig' sans préfixe @. Le thème custom étant listé en dernier, il a la priorité la plus haute ; le layout par défaut reste le fallback implicite pour tous les blocs non surchargés.

Vérification que la configuration est bien prise en compte :

bin/console debug:config twig

La section form_themes doit lister form/kirexo_theme.html.twig.

Mapping widget Symfony → classe DS

Le fichier templates/form/kirexo_theme.html.twig étend le layout par défaut via {% use 'form_div_layout.html.twig' %} et surcharge exactement sept blocs. Les classes DS citées sont définies dans assets/styles/kirexo-ds.css.

Bloc Symfony Couvre Classe DS appliquée
form_row conteneur d'un champ .field (+ .error si le champ porte des erreurs)
form_widget_simple text, email, password, url, number, search, tel… .input
textarea_widget zone de texte multiligne .textarea
choice_widget_collapsed <select> déroulant .select
form_help texte d'aide .hint
form_errors erreurs de champ / de formulaire .msg (champ) ou .notice warn (formulaire)
button_widget SubmitType / ButtonType .btn (base seule)

Détails par bloc

  • form_row enveloppe le champ dans un <div class="field">, lui ajoute la classe error quand errors|length > 0, puis rend dans l'ordre form_label → form_widget → form_help → form_errors. La classe .field.error active la bordure rouge sur le widget et la coloration du message d'erreur.

  • form_widget_simple ajoute .input. Les champs hidden passent par le bloc distinct hidden_widget (non surchargé) et ne reçoivent donc pas .input — comportement voulu.

  • form_errors rend deux markups différents selon le niveau :

    • erreur de champ (form is not rootform) → une <span class="msg"> par message ; la couleur rouge vient de .field.error .msg, l'état error étant posé par form_row ;
    • erreur globale du formulaire (form is rootform) → un encadré <div class="notice warn" role="alert"> avec sa <span class="bar"> et role="alert" pour l'accessibilité.

  • button_widget garantit uniquement la classe de base .btn. La variante (btn-primary, btn-secondary, btn-ghost) reste de la responsabilité de l'appelant : voir la convention ci-dessous.

Blocs volontairement non surchargés

Le thème ne touche pas aux blocs suivants, qui conservent leur rendu Symfony par défaut :

Bloc non surchargé Raison
checkbox_widget, radio_widget, choice_widget_expanded Le DS n'a pas de classe générique pour ces contrôles. Le picker d'accent (templates/admin/settings.html.twig) et le remember-me de /login rendent leurs radios/checkboxes via un markup enveloppant custom ; les styliser ici casserait ces écrans. Leur stylage relève des feuilles d'écran (screens.css), traité dans d'autres lots.
form_label Le DS cible le label par descendance (.field label) ; le <label> par défaut suffit, aucune classe à ajouter.
submit_widget Dans form_div_layout.html.twig il délègue déjà à button_widget. Le surcharger appliquerait .btn deux fois.

Convention : variante de bouton explicite

Le thème pose uniquement .btn. La variante visuelle est toujours passée explicitement, jamais déduite par le thème :

  • via l'option attr du champ bouton — attr: {class: 'btn-primary'} ;
  • ou via un <button class="btn btn-primary"> écrit directement dans le template (cas dominant du projet).

Ce choix garde le thème neutre : un même SubmitType peut être rendu en primaire, secondaire ou ghost selon le contexte d'appel, sans logique de variante cachée dans le thème.

Garde-fous d'accessibilité hérités

Les classes appliquées par le thème portent déjà les garanties RGAA du DS, à ne pas redéfinir :

  • .input, .textarea, .select ont une min-height de 44px et un anneau de focus visible ;
  • .btn a une min-height de 44px.

Voir Design system : tokens, thèmes et accent pour le détail des contraintes.

Voir aussi