Personnalisation des onglets dans les formulaires

Dokos permet désormais de personnaliser dynamiquement les onglets dans les formulaires grâce à deux nouveaux mécanismes : les overrides d'onglets et la résolution de l'onglet actif. Ces fonctionnalités sont particulièrement utiles pour adapter l'interface en fonction des données ou des permissions de l'utilisateur.

Override d'onglets (Tab.override)

L'override d'onglet permet de modifier dynamiquement la visibilité (hidden) ou le libellé (label) d'un onglet pour un rendu spécifique, sans altérer la structure originale du formulaire.

Cas d'usage

• Masquer un onglet si certaines conditions ne sont pas remplies (ex : un champ obligatoire non renseigné).
• Renommer un onglet en fonction du contexte (ex : "Commandes" → "Commandes en attente" si des filtres sont appliqués).

Exemple avec le client "Maison Verte SARL"

Supposons que vous souhaitez masquer l'onglet "Historique des paiements" pour les clients dont le solde est à jour.

1. Dans le script client du formulaire Client :

frappe.ui.form.on('Client', {
    refresh(frm) {
        // Vérifie si le solde est à jour
        if (frm.doc.outstanding_amount === 0) {
            // Applique un override pour masquer l'onglet
            frm.set_df_property('historique_paiements', 'hidden', 1, 'tab_override');
        }
    }
});

2. Résultat :

• Si le solde est à jour → l'onglet "Historique des paiements" n'apparaît pas.
• Si le solde est en retard → l'onglet reste visible.

::: info L'override est appliqué après la résolution des dépendances (depends_on), ce qui permet de lever dynamiquement un onglet masqué par une règle conditionnelle. :::

Résolution de l'onglet actif (update:activeTab)

Lorsque l'onglet demandé par l'utilisateur est masqué (via depends_on ou un override), Dokos sélectionne automatiquement le premier onglet visible. Le nouvel événement update:activeTab permet de suivre quel onglet est réellement affiché, ce qui est utile pour synchroniser d'autres éléments de l'interface.

Cas d'usage

• Mettre à jour un tableau de bord en fonction de l'onglet actif.
• Enregistrer la dernière position de l'utilisateur pour une navigation fluide.

Exemple avec le fournisseur "Bureau Moderne"

Dans un formulaire Fournisseur, si l'onglet "Contrats" est masqué (car aucun contrat n'est enregistré), Dokos bascule automatiquement vers l'onglet "Informations générales". Voici comment suivre ce changement :

// Dans un script client
frm.on('active_tab_change', (activeTab) => {
    frappe.show_alert({
        message: `Onglet actif : ${activeTab}`,
        indicator: 'blue'
    });
});

      
flowchart TD
    A[Utilisateur sélectionne
    l'onglet "Contrats"] --> B{L'onglet est-il
    masqué ?}
    B -->|Oui| C[Dokos sélectionne
    le premier onglet visible]
    B -->|Non| D[Affiche l'onglet "Contrats"]
    C --> E[Émet update:activeTab
    avec le nouvel onglet]

    

Bonnes pratiques

1. Évitez les overrides statiques : Préférez les règles dynamiques (depends_on) pour masquer des onglets, sauf si vous avez besoin d'un contrôle fin par rendu.
2. Conservez l'identité des onglets : Si vous renommez un onglet via label, son identité (utilisée dans les scripts) reste inchangée.
3. Testez les dépendances : Vérifiez que les overrides n'entrent pas en conflit avec les depends_on.

Fonctions utilitaires exportées

Dokos expose désormais deux fonctions pour travailler avec les onglets :

• tabStripLabel(tab) : Retourne le libellé affiché dans l'interface (ex : "Détails" pour un onglet sans libellé).
• resolveActiveTab(tabs, desiredTab) : Calcule l'onglet actif en tenant compte des masquages.

Exemple d'utilisation

const { tabStripLabel, resolveActiveTab } = frappe.ui.form;

// Affiche le libellé de l'onglet
console.log(tabStripLabel(frm.doc.__onload.tabs[0]));

// Résout l'onglet actif
const activeTab = resolveActiveTab(frm.doc.__onload.tabs, 'contrats');

::: dokos Cette fonctionnalité est réservée aux développeurs et administrateurs système. Pour l'utiliser, ajoutez du code JavaScript dans les Scripts clients ou les Scripts serveurs des formulaires concernés. :::