Insérer un composant personnalisé dans un formulaire FormLayout

Qu'est-ce qu'un « part » dans un formulaire FormLayout

Le composant FormLayout — utilisé notamment par la page d'enregistrement de Dokos — permet désormais à une application hôte de placer un composant Vue personnalisé (un « part » à l'intérieur de la structure du formulaire. Un part peut s'afficher de trois manières distinctes en fonction de l'endroit où vous le placez :

• Entre deux sections : le composant occupe toute la largeur du formulaire, comme un bloc plein cadre séparé.
• Dans une colonne : le composant occupe la largeur d'une cellule de la colonne, comme un champ à part entière.
• Avant ou après un champ existant : le composant s'ancre par rapport à un champ ou à un autre part déjà présent dans la colonne.

Comportements d'affichage

Habillage et libellés

L'affichage d'un part dépend de la présence d'un libellé ( label ) :

• Avec un libellé : le composant est encadré comme son voisin immédiat. Un part dans une colonne adopte l'allure d'un champ (libellé au-dessus de la cellule), tandis qu'un part entre les sections adopte l'allure d'un titre de section (libellé au-dessus du bloc pleine largeur).
• Sans libellé : le composant est affiché brut, sans cadre ni habillage.

Ordre et ancrage

Plusieurs parts peuvent s'ancrer par rapport au même champ ou au même part. Dans ce cas, l'ordre d'affichage respecte la logique suivante :

• Un part déclaré plus tardivement s'affiche plus près du champ ou du part auquel il s'ancre.
• Si un champ est masqué, le part qui lui est ancré conserve sa position sans être décalé.

      
flowchart LR
  A[Section 1] --> B[Part : Indicateur personnalisé]
  B --> C[Section 2]
  C --> D[Colonne A]
  C --> E[Colonne B]
  D --> D1[Champ : Montant TTC]
  D1 --> D2[Part : Barre de progression]
  D2 --> D3[Champ : Mode de règlement]

    

Règle de section vide

Une section contenant uniquement un part est désormais considérée comme non vide. Le part est pris en compte dans le calcul du contenu de la section, ce qui évite qu'une section ne disparaisse par erreur.

Exemple d'usage

L'exemple ci-dessous montre un formulaire de facture de vente dans lequel un indicateur personnalisé de solde client est inséré entre deux sections, et un graphique est placé dans une colonne, après le champ « Total » :

import { FormLayout, Section, Column, Part } from "@framework/ui"

export default {
  components: { FormLayout, Section, Column, Part },
  template: `
    <FormLayout>
      <Section title="Informations client">
        <Column>
          <Part label="Solde client" :component="CustomerBalanceWidget" />
        </Column>
      </Section>

      <Part label="Indicateurs de paiement" :component="PaymentIndicators" />

      <Section title="Montants">
        <Column>
          <Part :component="AmountChart" anchor="grand_total" />
        </Column>
      </Section>
    </FormLayout>
  `,
}

Exemple avec des données Dokos

Dans un formulaire de facture de vente pour le client Maison Verte SARL, un part « Solde client » placé dans la colonne « Informations client » affiche en temps réel l'encours commercial. Un autre part « Indicateurs de paiement » inséré entre les sections « Informations client » et « Articles » présente un graphique de répartition des règlements par mode (virement, chèque, prélèvement).

Cas d'usage courants

Limites actuelles

• Le composant Vue à afficher doit être fourni par l'application hôte ; aucun part n'est créé par défaut dans ui/.
• Cette fonctionnalité constitue la moitié « affichage » de la surface page.form de la page d'enregistrement de Dokos v2 ; la moitié « moteur » est livrée séparément.