Personnaliser les champs

Dokos offre plusieurs outils pour personnaliser les champs des types de documents (DocTypes) afin d'adapter l'interface à vos besoins métiers. Ces personnalisations peuvent être effectuées via l'interface utilisateur ou directement dans le code pour les développeurs et administrateurs.

Personnalisation via l'interface utilisateur

Ajouter ou modifier un champ

1. Allez dans Personnaliser le formulaire (recherchez dans la barre Awesome).
2. Sélectionnez le type de document à modifier (ex. : Facture de vente).
3. Ajoutez un nouveau champ ou modifiez un champ existant en définissant :
   • Libellé : Nom affiché à l'utilisateur.
   • Type : Type de champ (ex. : Lien, Date, Sélection).
   • Options : Pour les champs de type Lien, saisissez le type de document cible (ex. : Client).
   • Obligatoire : Cochez si le champ doit être rempli.
   • Masqué : Cochez pour masquer le champ.
4. Cliquez sur Mettre à jour pour enregistrer les modifications.

Filtres de lien (Link Filters)

Exemple — Maison Verte SARL Maison Verte SARL souhaite restreindre les choix de Fournisseur dans les Bons de commande aux seuls fournisseurs actifs. L'administrateur configure un filtre de lien pour n'afficher que les fournisseurs dont le statut est "Actif".

Les filtres de lien permettent de restreindre les valeurs disponibles dans un champ de type Lien en fonction de critères spécifiques. Par exemple, vous pouvez limiter les choix de Client aux seuls clients d'une certaine région ou d'un certain groupe.

Configurer un filtre de lien

1. Dans Personnaliser le formulaire, sélectionnez le type de document et le champ de type Lien à filtrer.
2. Dans le champ Filtres de lien, saisissez une liste de filtres au format JSON. Chaque filtre est une liste de 4 éléments :
   • Champ : Nom du champ sur lequel appliquer le filtre (ex. : status).
   • Opérateur : Opérateur de comparaison (ex. : =, in, !=).
   • Valeur : Valeur à comparer (ex. : "Actif", ["Actif", "En attente"]).
   • Condition : Condition logique (ex. : "and", "or").
   
   Exemple pour filtrer les fournisseurs actifs :

   [
     ["Supplier", "status", "=", "Actif"]
   ]
   

3. Cliquez sur Mettre à jour pour enregistrer.

Bon à savoir :

• Les filtres de lien sont appliqués côté serveur pour garantir la cohérence des données.
• Vous pouvez combiner plusieurs filtres avec des conditions "and" ou "or".
• Les filtres de lien sont également disponibles sur les champs de type Lien dans les Custom Fields, Property Setters et Customize Form.

Personnalisation avancée pour les développeurs

Définir des filtres de lien dans le code

Les filtres de lien peuvent également être définis directement dans le fichier JSON du DocType ou via un script Python. Voici un exemple pour un champ supplier dans un DocType Purchase Order :

{
  "fieldname": "supplier",
  "fieldtype": "Link",
  "label": "Fournisseur",
  "options": "Supplier",
  "link_filters": [
    ["Supplier", "status", "=", "Actif"]
  ]
}

Validation des filtres de lien

Depuis la version 16.0.0, Dokos applique une validation stricte des filtres de lien pour garantir leur conformité au format attendu. Cette validation est appliquée lors de :

• La création ou modification d'un DocType.
• L'ajout ou la modification d'un Custom Field.
• La configuration d'un Property Setter.
• La personnalisation d'un formulaire via Customize Form.

En cas de filtre invalide, une erreur est levée et les modifications ne sont pas enregistrées. Voici les cas couverts par la validation :

from frappe.core.doctype.doctype.doctype import validate_link_filters

link_filters = [
    ["Supplier", "status", "=", "Actif"]
]

try:
    validate_link_filters(link_filters)
    print("Filtre valide !")
except Exception as e:
    print(f"Erreur : {e}")

Bonnes pratiques

• Testez les filtres : Avant de déployer un filtre de lien en production, testez-le dans un environnement de développement pour vous assurer qu'il fonctionne comme prévu.
• Documentez les filtres : Si vous utilisez des filtres complexes, documentez leur logique pour faciliter la maintenance.
• Limitez les filtres : Évitez les filtres trop restrictifs qui pourraient empêcher les utilisateurs de sélectionner des valeurs valides.
• Utilisez des valeurs dynamiques : Pour les filtres dépendant du contexte (ex. : utilisateur connecté), utilisez des scripts côté client ou serveur pour générer les filtres dynamiquement.

Exemples concrets

Exemple 1 — Filtrer les articles par entrepôt

Cas d'usage — Bureau Moderne Bureau Moderne gère plusieurs entrepôts. Pour simplifier la saisie des bons de commande, l'administrateur configure un filtre de lien sur le champ Article pour n'afficher que les articles disponibles dans l'entrepôt sélectionné.

Configuration :

[
  ["Item", "warehouse", "=", "doc.warehouse"]
]

Exemple 2 — Filtrer les clients par groupe

Cas d'usage — Maison Verte SARL Maison Verte SARL souhaite restreindre les choix de Client dans les Factures de vente aux seuls clients du groupe "Particuliers".

Configuration :

[
  ["Customer", "customer_group", "=", "Particuliers"]
]

Exemple 3 — Combiner plusieurs filtres

Cas d'usage — Dupont Conseil Dupont Conseil souhaite afficher uniquement les Fournisseurs actifs et basés en France dans les Bons de commande.

Configuration :

[
  ["Supplier", "status", "=", "Actif", "and"],
  ["Supplier", "country", "=", "France"]
]

Résoudre les problèmes courants

Problème : Le filtre ne s'applique pas

• Vérifiez le format JSON : Assurez-vous que le filtre est saisi sous forme de liste JSON valide.
• Vérifiez les permissions : L'utilisateur doit avoir les permissions nécessaires pour accéder aux documents filtrés.
• Vérifiez les valeurs : Assurez-vous que les valeurs saisies dans le filtre existent bien dans la base de données.

Problème : Erreur de validation

• Consultez le message d'erreur : Dokos affiche un message clair en cas de filtre invalide.
• Corrigez le format : Assurez-vous que chaque filtre contient bien 4 éléments (champ, opérateur, valeur, condition).
• Testez en local : Utilisez un script Python pour valider le filtre avant de le déployer.

Problème : Performances lentes

• Limitez le nombre de filtres : Trop de filtres peuvent ralentir les requêtes.
• Utilisez des index : Assurez-vous que les champs utilisés dans les filtres sont indexés dans la base de données.
• Optimisez les requêtes : Pour les filtres complexes, envisagez d'utiliser des scripts côté serveur pour optimiser les performances.

Pour aller plus loin

• Personnaliser les formulaires : Guide complet sur la personnalisation des formulaires.
• Créer un type de document personnalisé : Tutoriel pour les développeurs.
• Documentation technique des DocTypes : Référence complète pour les administrateurs et développeurs.