Gestion des formulaires

Introduction

Les formulaires dans Dokos permettent de saisir et modifier des données de manière structurée. Cette page explique les fonctionnalités avancées liées à la gestion des formulaires, notamment la personnalisation des champs et le comportement des commits.

Personnalisation des champs

Structure des champs

Chaque champ dans un formulaire peut être configuré pour répondre à des besoins spécifiques. Voici les éléments clés à connaître :

• Types de champs : Texte, Numérique, Date, Table, Sélection multiple, etc.
• Comportement par défaut : Valeurs par défaut, champs obligatoires, masquage conditionnel.

Exemple de configuration

Pour configurer un champ de type Table dans un formulaire de commande client :

1. Accédez à Développeur > Doctype > Commande Client.
2. Ajoutez un champ de type Table et liez-le à un doctype enfant (ex: Articles de Commande).
3. Configurez les valeurs par défaut pour les lignes de la table.

Nouveautés dans la gestion des commits (v5)

Mécanisme de commit des champs

Depuis la version 5 de Dokos, un nouveau mécanisme de commit a été introduit pour améliorer la réactivité et la précision des formulaires. Voici ce qui change :

• Commit au niveau du champ : Chaque champ émet désormais un événement change lorsqu'une modification est validée (par exemple, après avoir quitté le champ ou appuyé sur Entrée).
• Séparation des clés serveurs et clients : Les identifiants des lignes dans une table sont désormais gérés séparément pour éviter les conflits entre les données côté client et côté serveur.
• Gestion des nouvelles lignes : Lorsqu'une nouvelle ligne est ajoutée dans une table, un identifiant temporaire (__row_id) est généré côté client. Cet identifiant est remplacé par un name côté serveur lors de l'enregistrement.

Impact sur les formulaires avec tables

Avant

• Les modifications dans une table étaient suivies globalement, ce qui pouvait entraîner des pertes de données ou des comportements inattendus (ex: sélection de lignes perdue après enregistrement).
• Les valeurs par défaut des champs enfants dans une table n'étaient pas appliquées automatiquement.

Après

• Précision des commits : Chaque cellule d'une table émet un commit avec le nom du champ et l'identifiant de la ligne concernée. Cela permet de suivre précisément les modifications.
• Conservation des sélections : Les sélections de lignes dans une table sont désormais conservées après un enregistrement, sauf pour la première sauvegarde d'une ligne ajoutée dans la session en cours.
• Application des valeurs par défaut : Les valeurs par défaut des champs enfants sont désormais appliquées correctement lors de l'ajout d'une nouvelle ligne.

Exemple d'utilisation

Prenons l'exemple d'un formulaire de Commande Client avec une table d'articles :

1. Ajout d'une nouvelle ligne :
   • Une nouvelle ligne est ajoutée à la table Articles de Commande.
   • Un identifiant temporaire (__row_id) est généré pour cette ligne.
   • Les valeurs par défaut (ex: quantité = 1, unité de mesure = "Unité") sont appliquées automatiquement.
2. Modification d'une cellule :
   • L'utilisateur modifie la quantité d'un article.
   • Un commit est émis avec le champ qty et l'identifiant de la ligne concernée.
3. Enregistrement du formulaire :
   • La ligne est enregistrée côté serveur et reçoit un name permanent.
   • Les sélections de lignes sont conservées.

      
flowchart TD
    A[Ajout d'une nouvelle ligne] --> B[Génération de __row_id]
    B --> C[Application des valeurs par défaut]
    C --> D[Modification d'une cellule]
    D --> E[Émission d'un commit]
    E --> F[Enregistrement du formulaire]
    F --> G[Remplacement de __row_id par name]
    G --> H[Conservation des sélections]

    

Bonnes pratiques

Pour les utilisateurs

• Valider les modifications : Après avoir modifié un champ, quittez-le ou appuyez sur Entrée pour déclencher le commit. Cela garantit que les modifications sont prises en compte.
• Vérifier les sélections : Après avoir enregistré un formulaire contenant une table, vérifiez que les sélections de lignes sont toujours actives.

Pour les développeurs

• Utilisation des événements : Si vous développez une fonctionnalité qui réagit aux modifications d'un formulaire, utilisez l'événement commit plutôt que de surveiller les changements globaux du document.
• Gestion des identifiants : Lors de la création de nouvelles lignes dans une table, utilisez l'identifiant temporaire (__row_id) pour suivre les modifications côté client avant l'enregistrement.

Dépannage

Problèmes courants

Journalisation des commits

Pour déboguer les commits émis par les champs, vous pouvez activer la journalisation dans la console du navigateur :

// Activer la journalisation des commits
frappe.ui.form.on('Commande Client', {
    refresh: function(frm) {
        frm.fields.forEach(field => {
            if (field.df.fieldtype === 'Table') {
                field.grid.grid_rows.forEach(row => {
                    row.docfields.forEach(docfield => {
                        frappe.model.on('commit', docfield.fieldname, (fieldname, value) => {
                            console.log(`Commit émis pour ${fieldname}:`, value);
                        });
                    });
                });
            } else {
                frappe.model.on('commit', field.df.fieldname, (fieldname, value) => {
                    console.log(`Commit émis pour ${fieldname}:`, value);
                });
            }
        });
    }
});

Conclusion

Le nouveau mécanisme de commit des champs dans Dokos v5 améliore la précision et la réactivité des formulaires, notamment pour les tables. En suivant les bonnes pratiques décrites ici, les utilisateurs et développeurs peuvent tirer pleinement parti de ces améliorations.

Pour plus d'informations sur la personnalisation des formulaires, consultez la section Personnalisation de l'interface.