Frappe Framework
Types de champs
Frappe propose de nombreux types de champs pour saisir et stocker des données dans un document. Cette page décrit chaque type, ses options et son usage.
Vue d’ensemble des types de champs
Frappe Framework propose une grande variété de types de champs (Field Types). Chacun répond à un cas d’usage précis et permet de saisir et de stocker un type de donnée différent dans un document. Les types de champs servent à afficher les composants aussi bien dans le bureau (Desk) que dans les Web Forms.
Le tableau ci-dessous résume les types disponibles ; chaque type est détaillé dans la suite de la page.
| Type de champ | Usage résumé |
|---|---|
| Data | Texte simple, 140 caractères maximum, validations Name / Email / Phone / URL / IBAN |
| Link | Lien vers un autre DocType (données maîtres) |
| Dynamic Link | Lien vers un document de n’importe quel DocType |
| Check | Case à cocher |
| Select | Liste déroulante à valeurs fixes |
| Table | Table enfant (child table) |
| Attach | Pièce jointe choisie dans le gestionnaire de fichiers |
| Attachment Gallery | Galerie des fichiers attachés au document |
| Attach Image | Image représentant le document |
| Text Editor | Éditeur de texte riche (WYSIWYG) |
| Date | Date |
| Datetime | Date et heure |
| Barcode | Code-barres généré à partir d’un numéro |
| Button | Bouton déclenchant une action |
| Code | Éditeur de code avec coloration syntaxique |
| Color | Sélecteur de couleur |
| Column Break | Saut de colonne (champ de mise en page) |
| Currency | Montant monétaire, jusqu’à 6 décimales |
| Float | Nombre décimal, jusqu’à 9 décimales |
| Geolocation | Carte avec polygones, lignes et points (GeoJSON) |
| HTML | Contenu HTML défini dans Options |
| Image | Affiche l’image d’un autre champ Attach |
| Int | Nombre entier |
| Small Text | Texte, limite supérieure à Data |
| Long Text | Texte sans limite de caractères |
| Text | Texte |
| Markdown Editor | Éditeur Markdown avec aperçu |
| Password | Donnée sensible (mot de passe, clé secrète) |
| Percent | Pourcentage |
| Rating | Notation par étoiles |
| Read Only | Valeur récupérée d’un autre formulaire, non modifiable |
| Section Break | Saut de section (champ de mise en page) |
| Tab Break | Saut d’onglet (champ de mise en page) |
| Signature | Signature numérique |
| Table MultiSelect | Sélection multiple de liens dans un seul champ |
| Time | Heure |
| Duration | Durée |
| JSON | Colonne JSON en base de données |
Détail de chaque type de champ
Data
Le champ Data est un champ texte simple. Il accepte une valeur de 140 caractères maximum, ce qui en fait le type le plus générique.
Vous pouvez activer une validation pour les types de données suivants en renseignant respectivement Name, Email, Phone ou URL dans les options :
| Option | Validation |
|---|---|
Name | Nom |
Email | Adresse e-mail |
Phone | Numéro de téléphone |
URL | Adresse URL |
IBAN | Formatage par blocs de 4 caractères |
Link
Un champ de lien (Link) est relié à un autre DocType maître dont il récupère les données. Par exemple, dans le DocType Quotation, le champ Customer est un champ Link. Pour en savoir plus, consultez la création d’un champ Link personnalisé.
Dynamic Link
Un champ de lien dynamique (Dynamic Link) peut rechercher et contenir la valeur d’un document de n’importe quel DocType. Le fonctionnement est détaillé dans la documentation ERPNext sur les champs Dynamic Link.
Check
Ce type ajoute une case à cocher. Si vous définissez la valeur Default à 1, la case est cochée par défaut.
Select
Le type « Select » crée une liste déroulante. Indiquez toutes les valeurs sélectionnables dans le champ Options, une valeur par ligne.
L’une de ces valeurs peut être recopiée dans le champ Default : elle sera alors sélectionnée par défaut dans un nouveau formulaire.
Si vous cochez Sort Options, les valeurs s’affichent par ordre alphabétique (dans la langue de l’utilisateur).
La documentation officielle illustre par des captures d’écran la définition d’un champ Select dans le DocType ou via Customize Form, puis son rendu dans un nouveau formulaire.
Table
Un champ « Table » permet d’afficher un autre DocType sous forme de table enfant (child table) dans votre formulaire.
- Choisissez ou définissez d’abord un DocType dont la case Is Child Table est cochée.
- Ajoutez ensuite un champ de type « Table » et indiquez le nom de ce DocType enfant dans le champ Options.
Par exemple, ERPNext définit un DocType enfant « Purchase Receipt Item » avec Is Child Table activé. Le DocType « Purchase Receipt » possède un champ de type « Table » dont les Options valent « Purchase Receipt Item ». La table enfant est alors affichée dans le formulaire Purchase Receipt.
Attach
Le champ Attach permet de parcourir le gestionnaire de fichiers (File Manager) et d’y choisir un fichier à joindre au document.
Attachment Gallery
Le champ Attachment Gallery affiche les fichiers attachés au document courant dans une galerie adaptative. Les images apparaissent sous forme de vignettes et peuvent être ouvertes dans un aperçu agrandi. Les autres types de fichiers apparaissent sous forme de cartes et s’ouvrent dans un nouvel onglet.
Les utilisateurs disposant du droit d’écriture peuvent téléverser et supprimer des pièces jointes directement depuis la galerie. Activer Read Only masque ces actions. Le document doit être enregistré avant de pouvoir téléverser des fichiers.
Par défaut, la galerie affiche toutes les pièces jointes du document. Utilisez Filters pour restreindre les enregistrements File affichés. Par exemple, pour n’afficher que les fichiers PDF :
[["File", "file_type", "=", "PDF"]]Pour n’afficher que les fichiers téléversés via une galerie donnée, filtrez sur attached_to_field avec le nom du champ de la galerie :
[["File", "attached_to_field", "=", "marketing_assets"]]Activez Make Attachment Public (by default) si les fichiers téléversés via la galerie doivent être publics par défaut.
Attach Image
Le champ Attach Image permet de joindre des images (jpeg, png, etc.). L’image devient l’image représentative du document pour ce DocType. Par exemple, pour afficher l’image d’un article (Item) dans son DocType, utilisez un champ Attach Image.
Text Editor
Text Editor est un champ texte qui affiche un éditeur WYSIWYG pour la saisie, avec diverses options de mise en forme.
Date
Ce champ permet de saisir une date.
Date and Time
Ce champ propose un sélecteur de date et d’heure. La date et l’heure courantes (fournies par votre ordinateur) sont renseignées par défaut.
Barcode
Ce champ permet de saisir un numéro de code-barres. Une fois le numéro saisi, le code-barres correspondant est généré automatiquement.
Button
Ce champ place un bouton dans le document. Il sert à exécuter des actions précises, par exemple publier un article de blog ou déclencher un traitement.
Code
Ce type sert à saisir du code. Un éditeur de code est affiché dans le formulaire du document. Vous pouvez indiquer un langage dans les options du champ pour activer la coloration syntaxique ; par exemple un champ Code avec les options définies à Python.
Vous pouvez activer une validation syntaxique de base pour les langages suivants en renseignant « Option » :
| Option | Usage |
|---|---|
Python | Scripts |
PythonExpression | Expressions simples sur une ligne qui doivent produire une valeur, p. ex. la condition d’une règle d’affectation (Assignment Rule) |
Différences entre Python et PythonExpression :
variable = 42est un codePythonvalide, mais pas unePythonExpressionvalide, car l’affectation ne produit aucune valeur ;variable == 42est à la fois un codePythonvalide et unePythonExpressionvalide, car l’expression produit une valeur.
Color
Ce champ permet à l’utilisateur de choisir une couleur via un sélecteur de couleur ou de saisir directement un code hexadécimal.
Column Break
Il s’agit d’un type de champ « meta » qui ne stocke aucune donnée : il indique un saut de colonne dans la vue ou le formulaire du document. La documentation officielle en montre le résultat par des captures d’écran.
Currency
Le champ Currency contient une valeur numérique, comme un prix d’article ou un montant. Il accepte jusqu’à six décimales et peut afficher le symbole de la devise.
Float
Le champ Float contient une valeur numérique avec jusqu’à neuf décimales.
Geolocation
Un champ Geolocation affiche une carte sur laquelle vous pouvez dessiner des polygones, des lignes et des points. Les données sont stockées sous forme de feature_collection GeoJSON.
Si vous ajoutez un champ Geolocation nommé exactement location, vous obtenez une vue carte supplémentaire (l’équivalent de la vue liste, mais sur une carte). Cela fonctionne aussi si vous créez deux champs séparés nommés latitude et longitude.
À retenir
Frappe utilise la bibliothèque « Leaflet », qui stocke les coordonnées sous la forme [latitude, longitude], soit l’inverse de la convention habituelle de GeoJSON.
HTML
Ce champ affiche le contenu saisi dans Options comme HTML dans le formulaire ou la page de vue du document. La documentation officielle en montre un exemple par des captures d’écran.
Image
Le champ Image affiche un fichier image sélectionné dans un autre champ de type Attach.
Dans le DocType, l’option (Option) du champ Image doit contenir le nom du champ auquel l’image est attachée. Le champ Image affiche alors l’image référencée par la valeur de ce champ.
Int (entier)
Le champ entier (Int) contient une valeur numérique sans décimale.
Small Text
Le champ Small Text contient du texte, avec une limite de caractères supérieure à celle du champ Data.
Long Text
Utilisez un champ Long Text pour saisir des données sans limite de caractères.
Text
Ce type permet d’ajouter du texte dans le champ. La limite de caractères des champs Small Text, Long Text et Text dépend du système de gestion de base de données relationnelle utilisé.
Markdown Editor
Ce champ permet de saisir du texte en Markdown. Il propose aussi une vue Preview du HTML rendu.
Password
Le champ Password contient une valeur encodée. Il sert à stocker des données sensibles : mots de passe, phrases secrètes, clés secrètes, etc.
Percent
Un champ Percent est calculé en arrière-plan comme un pourcentage.
Rating
Ce champ affiche une notation interactive par étoiles. Par défaut, 5 étoiles sont affichées ; vous pouvez changer ce nombre en saisissant une valeur de 3 à 10 dans les options du champ.
Les demi-notes sont aussi possibles, par exemple 3,5 sur 5.
Read Only
Un champ Read Only contient une donnée récupérée depuis un autre formulaire et non modifiable. Utilisez ce type lorsque la source de la valeur est prédéterminée.
Section Break
Section Break divise le formulaire en plusieurs sections. Tous les champs qui suivent un Section Break (jusqu’au prochain Section Break) font partie de la nouvelle section.
Tab Break
Tab Break divise le formulaire en plusieurs onglets. Tous les champs qui suivent, jusqu’au prochain Tab Break, font partie du nouvel onglet.
À retenir
Si la table fields d’un DocType ne commence pas par un Tab Break, un Tab Break par défaut nommé Details est utilisé. Cela ne se produit que si le DocType possède au moins un Tab Break dans sa table fields.
Signature
Le champ Signature permet d’ajouter une signature numérique. Consultez la documentation du champ Signature pour en savoir plus.
Table MultiSelect
Ce type combine les champs de type « Link » et « Table ». Au lieu d’une table enfant avec un bouton « Add Row », plusieurs valeurs peuvent être sélectionnées dans un seul champ.
Time
Champ de saisie d’une heure.
Duration
Utilisez le champ Duration pour définir une durée.
Si vous ne souhaitez pas suivre la durée en jours ou en secondes, activez respectivement les options « Hide Days » et « Hide Seconds » dans votre formulaire. Un jour équivaut à 24 heures.
JSON
Ce type crée une colonne de type JSON dans votre base de données. Il ajoute aussi la coloration syntaxique dans les contrôles du bureau.