DocType Layout

À quoi sert DocType Layout

DocType Layout permet de créer plusieurs vues de formulaire pour un même DocType, chacune avec ses propres libellés, règles de visibilité et valeurs par défaut, sans modifier le DocType lui-même. Les layouts s’activent automatiquement selon l’état du document : la bonne vue apparaît sans action manuelle.

Cas d’usage courants :

• une vue de saisie simplifiée qui masque les champs avancés ;
• une vue de relecture qui renomme les champs pour plus de clarté ;
• un basculement automatique vers un layout « Retour » lorsque doc.is_return == 1 ;
• des layouts spécifiques à un état ou à un contexte, pilotés par des conditions ou des liens d’espace de travail (Workspace).

Créer un layout

Ouvrez la liste DocType Layout et cliquez sur New.

Après avoir choisi un Document Type, cliquez sur Sync Fields pour importer tous les champs du DocType. Un constructeur de formulaire visuel s’ouvre dans l’onglet Parent Layout, où vous pouvez réordonner et configurer les champs.

Surcharger les propriétés des champs

Dans le constructeur de formulaire, sélectionnez un champ pour surcharger ses propriétés. Les propriétés suivantes peuvent être définies par layout sans affecter le DocType de base :

Les propriétés non définies dans le layout reprennent la valeur du DocType de base.

Bascule automatique de layout

La sélection du layout est entièrement pilotée par les conditions : il n’y a pas de sélecteur manuel. Définissez une Condition pour qu’un layout s’active automatiquement lorsque l’expression est vraie après un rafraîchissement du formulaire :

// Activates for return transactions
doc.is_return == 1

// Activates for high-value orders
doc.grand_total > 100000

// Activates for a specific status
doc.status === "Closed"

Lorsqu’une condition correspond, le layout est appliqué et l’URL est mise à jour avec ?layout=<name>. Le premier layout dont la condition correspond l’emporte ; les layouts sont évalués dans l’ordre où ils apparaissent dans la liste. Un badge indicateur de layout apparaît à côté du titre du document dès qu’un layout non par défaut est actif.

Navigation par fil d’Ariane

Lorsqu’un layout est actif, le fil d’Ariane (breadcrumb) le reflète :

• dans la vue formulaire, le titre du layout apparaît comme un élément cliquable entre le DocType et le nom du document. Un clic ouvre la liste filtrée selon la condition du layout (déduite des expressions de la forme doc.field OP value) ;
• dans cette liste filtrée, le titre du layout apparaît comme un élément non cliquable, pour garder le contexte actif visible ;
• cliquer sur l’élément DocType alors qu’un layout est actif efface tous les filtres et retire l’élément de layout, pour revenir à la liste non filtrée.

Layouts de tables enfants

Un layout peut spécifier des layouts différents pour ses tables enfants. Dans l’onglet Child Layouts, ajoutez une ligne pour chaque table enfant à personnaliser :

Lorsque le layout parent est actif, chaque grille de table enfant est rendue automatiquement avec le layout enfant assigné, en appliquant les mêmes surcharges au niveau des champs qu’un layout parent.

> [!WARNING] > Le Document Type du layout enfant doit correspondre au DocType de la table enfant (p. ex. Sales Invoice Item), et non au DocType parent. Créez d’abord un layout séparé pour la table enfant, puis référencez-le ici.

Les mêmes propriétés de champ que sur un layout parent (label, hidden, reqd, read_only, depends_on, ordre des colonnes, etc.) s’appliquent dans la grille lorsque le layout enfant est actif.

Exemple : un layout parent Finance View associe la table des articles à un layout enfant Compact Items qui masque description, uom et d’autres colonnes de détail, pour ne laisser visibles que item_code, qty et amount. Le passage au layout parent compacte automatiquement la grille, sans action supplémentaire de l’utilisateur.

Héritage de layout

Utilisez Based On pour hériter de la configuration des champs d’un autre layout du même DocType. Le layout enfant part de l’ordre des champs et des surcharges du parent, et peut ensuite personnaliser des champs individuels ou en ajouter.

C’est utile pour créer une famille de layouts liés : définissez un Base Layout avec l’ordre des champs commun, puis créez des layouts spécialisés (p. ex. Sales View, Finance View) qui en héritent et l’ajustent.

Garder les champs synchronisés

Le bouton Sync Fields compare la liste des champs du layout avec la définition actuelle du DocType et signale :

Lancez cette synchronisation après toute modification du DocType sous-jacent pour garder le layout cohérent.

Intégration aux espaces de travail

Tout lien vers un DocType dans la barre latérale d’un espace de travail (Workspace) peut être associé à un layout précis. Ouvrez l’espace de travail en mode édition, sélectionnez un lien de DocType et renseignez le champ DocType Layout avec le layout souhaité. Un clic sur ce lien ouvre la liste limitée à ce layout (l’URL porte ?layout=<name>), et les nouveaux documents créés depuis cette liste s’ouvrent avec ce layout.

Pour les développeurs : layouts standard

Les layouts peuvent être livrés avec une app en cochant Is Standard et en choisissant un Module. En mode développeur, l’enregistrement d’un layout standard l’exporte automatiquement sous forme de fichier JSON vers :

{app}/{module}/doctype/{doctype}/doctype_layout/{layout_name}.json

Ce fichier est inclus dans les migrations et déployé automatiquement via bench migrate. Les layouts standard sont en lecture seule sur les instances de production (hors mode développeur).

Pages liées

• DocField : les propriétés depends_on, mandatory_depends_on, read_only_depends_on.
• Personnaliser les DocTypes
• Espaces de travail
• bench migrate