Développeurs

Scripts et appartenance des composants Studio

Référence développeur : écrire le script d'un composant Studio (props, emits, setup), comprendre à quelle application il appartient, le renommer, le déplacer, le supprimer et migrer les anciennes lignes d'entrée.

Scripts et appartenance des composants Studio

Un composant Studio (DocType Studio Component) est un arbre de blocs réutilisable. Il peut aussi avoir un script qui garde son propre état, ses valeurs calculées et ses gestionnaires, et qui envoie des événements à la page. Cette page décrit le script, les props, l'application propriétaire du composant et la migration des anciennes lignes d'entrée.

L'éditeur Studio (/studio) n'est pas traduit : ses libellés et ses messages sont en anglais.

Script d'un composant

Le champ Script du composant contient un module JavaScript. Son export par défaut est une définition de composant Vue sans modèle : les blocs du composant forment le modèle.

import { ref, computed } from "vue"

export default {
    props: {
        title: { type: String, required: true },
        price: { type: Number, default: 0 },
        max: { type: Number, default: 5 },
    },
    emits: ["change"],
    setup(props, { emit }) {
        const quantity = ref(0)
        const canAdd = computed(() => quantity.value < props.max)

        function add() {
            quantity.value += 1
            emit("change", quantity.value)
        }

        return { quantity, canAdd, add }
    },
}
  • Un bloc lit une prop avec {{ props.title }} et une valeur retournée par setup par son nom, par exemple {{ quantity }}. inputs est l'ancien nom de props et fonctionne encore.
  • setup s'exécute dans une instance de composant Vue : ref, computed, watch et les fonctions de cycle de vie fonctionnent. Un setup asynchrone fonctionne sans <Suspense>.
  • setup doit retourner un objet. Une fonction retournée est refusée.
  • Le script accepte seulement props, emits et setup. Une autre clé provoque l'erreur « A component script cannot use … Use only props, emits and setup. ». setup doit être une fonction.
  • Un composant lit ses propres props et les valeurs de son setup, les emplacements (par exemple dataItem) et les aides intégrées route, router, socket, toast et call.
  • Si un script mis à jour ne se charge pas ou n'est pas valide, Studio garde le dernier script qui fonctionnait et affiche l'erreur dans l'éditeur.

Props

Un composant déclare ses props uniquement dans son script. Le formulaire des props de l'éditeur lit les props du script et y écrit les modifications.

  • Une prop a un type Vue (String, Number, Boolean, Array, Object…).
  • Une prop peut avoir un contrôle d'édition, gardé dans la clé meta de la prop : control (textarea, select ou color pour une prop String), options (liste des choix d'un select) et description.
  • Changer le type d'une prop dans le formulaire supprime sa valeur par défaut et son contrôle.
  • Le formulaire ne peut pas modifier une prop construite à partir d'une variable ou d'un spread : modifiez-la dans le script.
  • Les valeurs d'aperçu (Preview values) montrent le composant avec des données dans l'éditeur de composant. Studio ne les enregistre pas.
export default {
    props: {
        columns: { type: Number, default: 3 },
        size: {
            type: String,
            default: "md",
            meta: { control: "select", options: ["sm", "md", "lg"], description: "Taille de la grille" },
        },
    },
}

Anciennes lignes d'entrée

Le tableau Inputs (libellé non traduit, DocType Studio Component Input) est conservé pour compatibilité et est en lecture seule. Un composant sans script prend ses props de ces lignes, sans type.

  • Ajouter ou modifier une ligne est refusé : « You cannot add or edit input rows. Define props in the component's script instead. » (message non traduit). Cette règle ne s'applique pas à l'import des fichiers d'une application, qui peut encore apporter des lignes.
  • Le correctif frappe.studio.doctype.studio_component.patches.move_inputs_to_script_props (déclaré dans frappe/patches.txt) s'exécute pendant bench migrate. Pour chaque composant créé sur le site (non standard) qui a des lignes et pas de script, il écrit une prop par ligne dans le script, puis supprime les lignes. Les types text, textarea, select et color deviennent String, number devient Number et checkbox devient Boolean.
  • Le correctif ignore un composant dont une valeur par défaut n'a pas d'équivalent comme défaut de prop : une valeur qui contient une liaison {{ }}, ou une valeur par défaut sur une ligne de type nombre ou case à cocher. Il liste ces composants dans la console ; déclarez leurs props dans un script.
  • Le correctif ignore aussi les composants standard (exportés) : leur fichier JSON est leur source, donc le dépôt de l'application doit changer.

Application propriétaire

Le champ Studio App (libellé non traduit) d'un composant désigne l'application qui le possède. Il ne peut être défini qu'à la création.

Dans l'éditeur, la fenêtre Create Component a une case Global Component. Si la case est décochée, le composant appartient à l'application ouverte. Dans les réglages d'un composant, l'interrupteur Global component déplace le composant (voir Déplacer un composant).

CasNom du documentDisponibilité
Composant d'application<application>/<identifiant>Les pages et composants de cette application.
Composant global (sans application)<identifiant>Toutes les applications du site, et en dehors d'une application.
  • L'identifiant (component_id, en lecture seule) est unique dans son application. Deux applications peuvent donc avoir chacune un composant card. Sans identifiant fourni, Studio le déduit du nom du composant et ajoute un numéro si l'identifiant existe déjà dans la même application.
  • Les blocs désignent un composant par son identifiant. Pour une application, le composant propre à l'application passe avant un composant global de même identifiant.
  • Renommer le document renomme l'identifiant : Studio renomme les fichiers exportés du composant (JSON et script) et met à jour les blocs des pages et des composants qui l'utilisent. Le nouveau nom peut être l'identifiant seul ; un composant ne peut pas changer d'application par un renommage, et deux composants ne peuvent pas être fusionnés.
  • Renommer une application renomme ses composants (le nom du document contient le nom de l'application) et réexporte leurs fichiers.
  • Le champ virtuel Nom du dossier de Studio App (libellé non traduit) (masqué, en lecture seule) donne le dossier de l'application dans le dossier studio de son application Frappe.

Composant global : limites

Un composant global s'affiche dans toutes les applications, il ne peut donc pas dépendre des fichiers d'une seule :

  • L'enregistrement est refusé (« Script not saved », titre non traduit) si son script importe @app/… ou un chemin relatif. Importez seulement des bibliothèques comme vue.
  • Si vous modifiez ses blocs et qu'ils utilisent un composant Vue .vue de l'application, Studio affiche un avertissement : le composant ne fonctionnera pas dans les autres applications.

Déplacer un composant

La méthode Studio Component.set_app(studio_app=None) (accessible via frappe.whitelist) déplace un composant global vers une application, ou rend global un composant d'application quand aucune application n'est donnée.

  • Elle exige le droit d'écriture sur le composant et, pour une application cible, sur cette application.
  • L'identifiant ne change pas : le nom du document change, pas les blocs qui l'utilisent.
  • Rendre un composant global échoue si un composant global avec le même identifiant existe déjà.
  • Quand une autre application utilise le composant global, celui-ci reste en place à côté de la copie de l'application. Le retour est {"name": <nouveau nom>, "is_global_kept": <booléen>}.

Supprimer un composant

La suppression d'un composant est refusée (« Component not deleted », titre non traduit) tant qu'une page ou un autre composant contient un bloc qui le désigne. Le message liste les titres, suivis d'un décompte des utilisations que vous n'avez pas le droit de lire. Studio Component.get_usages() retourne ces titres (None pour une utilisation illisible). Supprimer une application supprime ses composants, qui peuvent s'utiliser entre eux. En mode développeur, la suppression retire aussi les fichiers exportés du composant.

Fichiers du composant

  • Le script d'un composant apparaît dans l'explorateur de fichiers de l'éditeur sous studio_components/<identifiant>.js, que l'application soit en base de données ou exportée. Les API de fichiers (list_studio_files, read_studio_file, write_studio_file) lisent et écrivent le champ Script. L'explorateur liste les composants à script que les pages de l'application utilisent. Une écriture avec un hachage connu est refusée (« {0} changed since you opened it. ») si le script a changé entre-temps.
  • Pour une application exportée, le dossier studio_components/ contient <identifiant>.json et le script <identifiant>.js. Dans une application exportée, le fichier est la copie que le développeur modifie : Studio ne le remplace que si le champ Script a changé, et un fichier existant garde son langage. Un nouveau fichier est en JavaScript.
  • Dans une application exportée, écrire, renommer ou supprimer studio_components/<identifiant>.js par les API de fichiers met aussi à jour le champ Script du composant.
  • L'export d'une page standard écrit dans studio_components/ les composants que ses blocs utilisent (celui de l'application, sinon le global) et les marque standard. Il supprime les fichiers (JSON et script) des composants qu'aucune page de l'application n'utilise. Le JSON ne contient ni le script ni les champs virtuels.
  • La compilation de l'application Studio inclut les scripts des composants : les fichiers studio_components/ d'une application exportée, ou le champ Script des composants utilisés par les pages d'une application en base de données.

Copier-coller des blocs entre applications

Un bloc copié emporte les composants qu'il utilise, avec leur script.

  • Au collage dans une autre application, un composant d'application devient un composant de l'application cible (<application cible>/<identifiant>). Un composant global reste global.
  • Si un composant de même nom existe déjà avec un contenu différent (nom, blocs, script, désactivation ou lignes d'entrée), la fenêtre Pasted block conflicts s'ouvre. Keep existing garde le composant existant. Use copied le remplace : les blocs des autres pages qui l'utilisent changent aussi.

Migrer les composants globaux d'une application exportée

Les composants exportés avant l'introduction de l'appartenance n'ont pas d'application : ils sont globaux. Dans le dépôt de l'application Frappe, pour chaque fichier de <application_frappe>/studio/<application_studio>/studio_components/ :

  1. Lisez le nom de l'application dans le champ name de <application_studio>.json (le dossier porte le nom normalisé, mon-app donne mon_app).
  2. Dans le JSON du composant, ajoutez studio_app, remplacez name par <application>/<identifiant> et définissez is_standard à 1. Ne changez ni component_id, ni le nom des fichiers, ni les pages.
  3. Convertissez les lignes inputs en props dans studio_components/<identifiant>.js, puis retirez la clé inputs du JSON. La valeur par défaut d'une ligne est un texte : écrivez default: "md" pour du texte, default: 3 ou default: true pour un nombre ou une case à cocher, et une fonction pour un tableau ou un objet. Utilisez null comme type quand la valeur peut être un tableau ou un objet.
  4. L'import crée le composant d'application et laisse l'ancien enregistrement global. Ajoutez un correctif à l'application qui appelle sync_studio_apps("<application>") d'abord, puis supprime chaque ancien enregistrement avec frappe.delete_doc("Studio Component", <identifiant>, force=True). Ne supprimez pas un composant global qu'une application en base de données du site peut utiliser (identifiant générique comme header).
  5. Vérifiez : bench --site <site> migrate, ouverture des pages dans l'éditeur et publiées, puis bench build --app <application_frappe>.

Un composant peut aussi cesser de lire les variables, ressources et fonctions de la page : passez les données par des props, déclarez des emits pour les actions de la page, et gérez l'événement dans les événements du bloc sur la page.

Exemple

Exemple fictif. L'application boutique a un composant carte_produit avec un compteur.

  1. Créez le composant dans l'application boutique : son nom de document est boutique/carte_produit.
  2. Dans son script, déclarez la prop title, l'événement change et le setup de l'exemple ci-dessus.
  3. Dans un bloc texte du composant, saisissez {{ props.title }} : {{ quantity }}.
  4. Sur la page, ajoutez le composant, renseignez title et gérez l'événement change dans les événements du bloc.

Une autre application du site peut avoir son propre carte_produit sans conflit.