Îlot d'application

Un îlot (island) est une interface Vue qu'une application construit et qu'un hôte monte dans un shadow root. L'hôte est le bureau (desk) ou une autre application frappe-ui. L'îlot apporte sa propre copie de Vue et de frappe-ui : les styles de l'îlot et ceux du bureau ne se mélangent pas.

      
flowchart LR
    A[Application : build-islands.mjs] --> B[assets.json : nom.island.js / nom.island.css]
    B --> C[Bureau : frappe.ui.mount_island]
    B --> D[App Vue : composant Island]
    C --> E[Shadow root + application Vue]
    D --> E

    

Pour une page du bureau entièrement dessinée par une île, voir Îles (Islands).

1. Écrire le point d'entrée

// apps/mon_app/frontend/src/islands/apercu.js
import { mountVueIsland } from "@framework/ui/island";
import Apercu from "./Apercu.vue";

export const mount = (el, context) => mountVueIsland(el, { ...context, component: Apercu });

mountVueIsland ouvre le shadow root, charge la feuille de style de l'application et suit le thème de l'hôte. Passez configure(app) pour enregistrer des plugins, et routes si l'île a sa propre navigation. Dans un composant, useHost() renvoie le contexte de l'hôte : locale, timezone, user, theme, navigate.

2. Construire l'île

// apps/mon_app/frontend/build-islands.mjs
import { buildIslands } from "@framework/ui/vite/island";

await buildIslands({
    app: "mon_app",
    root: import.meta.dirname,
    entries: { "mon_app.apercu": "src/islands/apercu.js" },
    production: process.argv.includes("--production"),
    watch: process.argv.includes("--watch"),
});

Le nom de l'entrée est le nom de l'île. Le build écrit mon_app.apercu.island.js et mon_app.apercu.island.css dans assets.json : c'est l'enregistrement de l'île. Aucun hook n'est nécessaire. Préfixez le nom par celui de l'application : tous les noms partagent un même espace sur le bench.

Ajoutez aussi le correctif de reka-ui livré par le paquet, dans le package.json du frontend :

"postinstall": "patch-package && patch-package --patch-dir node_modules/@framework/ui/patches"

Sans lui, un popover ouvert au-dessus d'une boîte de dialogue ferme la boîte.

3. Monter l'île

Dans le bureau :

const island = frappe.ui.mount_island("mon_app.apercu", el, {
    invoice: frm.doc.name,
    onTitle: (title) => frappe.utils.set_title(title),
});
island.update({ invoice: autre_facture });
// island.unmount() pour libérer

Le troisième argument est l'objet des propriétés de l'île. island.ready est une promesse rejetée si l'île ne se charge pas. Une île n'est disponible que si son application est installée sur le site.

Dans une application frappe-ui :

<Island name="mon_app.apercu" :invoice="invoice" :context="{ user, locale }" @title="title = $event" />

Pour afficher une île dans un formulaire sans code, utilisez un champ « Composant Vue ».

Titre et actions d'une île de page

Une île qui remplit une page ne dessine pas d'en-tête. Elle signale deux valeurs, et l'hôte construit le titre et le menu de la page :

• title : texte ou null ;
• actions : liste de { label, icon?, onClick } ou { label, icon?, href }.

Dans le bureau, passez onTitle et onActions. Une action avec href s'ouvre dans un nouvel onglet.

Dessiner un document du bureau avec une île

Le bureau dessine lui-même les documents Dashboard et Dashboard Chart. Une application peut les dessiner avec son île. Elle place __onload.island depuis un gestionnaire onload déclaré dans doc_events :

# mon_app/hooks.py
doc_events = {"Dashboard": {"onload": "mon_app.desk.island.dashboard"}}

# mon_app/desk/island.py
def dashboard(doc, method=None):
    if doc.get("mon_app_dashboard"):
        doc.set_onload("island", {"name": "mon_app.dashboard", "props": {"dashboard": doc.mon_app_dashboard}})

Exemple fictif : mon_app_dashboard est un champ personnalisé de votre application. Sans la clé island, le bureau affiche le document normalement. Dans un widget de graphique, le bureau garde le cadre (titre, menu, erreurs) et l'île dessine le corps.