Champ « Composant Vue »
Champ « Composant Vue »
Le type de champ « Composant Vue » affiche une île Vue publiée par une application directement dans le formulaire d'un document. L'île reçoit une copie du document et se met à jour au fur et à mesure des modifications de l'utilisateur, y compris avant l'enregistrement.
Le champ est réservé à l'affichage, comme le type « HTML » :
- il ne crée pas de colonne en base de données et ne stocke aucune valeur ;
- l'île reçoit une copie du document (tables enfants comprises) et ne renvoie jamais de valeur vers le document ;
- le champ reste visible lorsqu'il est vide et en lecture seule : il n'est pas masqué par le paramètre d'affichage qui masque les champs vides en lecture seule ;
- le champ ne possédant aucune valeur, il est ignoré lors des imports de données.
Prérequis
- Une application installée sur le site publie une île Vue (voir Îles Vue). Son nom suit le format
application.nom_de_lile, par exemplemon_appli.apercu_facture(exemple fictif). - Les composants créés dans Studio ne sont pas publiés en tant qu'îles : ils ne peuvent pas être utilisés avec ce type de champ.
Créer un champ « Composant Vue »
Le type « Composant Vue » figure dans la liste des types de champ :
- du DocType, dans le code de l'application ;
- du champ personnalisé ;
- de la personnalisation de formulaire.
Renseignez le champ Options avec le nom exact de l'île, de la même manière qu'un champ « Lien » indique un type de document :
{
"fieldname": "apercu_facture",
"label": "Aperçu",
"fieldtype": "Vue Component",
"options": "mon_appli.apercu_facture"
}
Dans le constructeur de formulaire, les options d'un champ « Composant Vue » proposent directement la liste des îles disponibles sur le site, et un aperçu du champ est affiché.
Validation à l'enregistrement
Lors de l'enregistrement d'un DocType, d'un champ personnalisé ou d'une personnalisation de formulaire, le champ est vérifié :
- le champ Options est obligatoire ;
- le nom indiqué doit correspondre à une île publiée sur le site, sinon l'enregistrement est refusé.
Cette vérification n'est pas exécutée pendant les correctifs (patches), l'import des fixtures ou l'installation d'une application. Si l'île devient indisponible après la création du champ, le formulaire affiche à sa place le message « "{0}" is not available on this site. ». Le reste du formulaire fonctionne normalement.
Propriétés reçues par l'île
L'île montée dans le formulaire reçoit les propriétés suivantes :
| Propriété | Type | Description |
|---|---|---|
doctype | string | Type de document du formulaire |
name | string | null | Nom du document, null tant que le document n'est pas enregistré |
doc | object | Copie JSON du document, tables enfants comprises |
is_new | boolean | true si le document n'est pas encore enregistré |
read_only | boolean | true si le champ n'est pas en écriture pour l'utilisateur |
Cycle de vie de l'île
- L'île est montée une seule fois à l'affichage du champ, via
frappe.ui.mount_island(nom, conteneur, props). - Lorsque le document est modifié dans le formulaire, l'île reçoit les nouvelles propriétés par
island.update(props); les modifications sont regroupées avec un délai de 300 ms. - Si les options du champ changent, l'île précédente est démontée et la nouvelle est montée.
- Si le chargement de l'île échoue, un message est affiché à la place du composant et le nom de l'île n'est pas retenté pour ce champ.
- Lorsque le champ est retiré du DOM, l'île est démontée par
island.unmount().
Comme l'île ne reçoit qu'une copie du document, elle ne peut pas modifier le document : toute interaction doit passer par les mécanismes habituels du formulaire (script client, API) en complément de ce champ d'affichage.