Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Développeurs

Package @framework/ui

Intégrer le paquet Vue @framework/ui de Dodock dans le frontend d'une application, et connaître ses composants et ses sous-chemins.

Package @framework/ui

@framework/ui regroupe les composants Vue et les utilitaires partagés par les frontends des applications Frappe et Dodock. Il complète frappe-ui avec les composants qui dépendent d'un serveur Frappe : champ de lien, formulaires, listes, filtres, import de données…

Ce paquet concerne les développeurs d'applications. Il ne concerne pas les utilisateurs finaux.

Principe

Le paquet se trouve dans le dossier ui/ de l'application frappe (Dodock). Il n'est pas publié sur npm. Il est livré en sources (.vue, .ts) : le bundler de votre application (Vite) le compile avec votre code.

vue, vue-router, frappe-ui, reka-ui et @vueuse/core sont des dépendances paires (peer dependencies) : le paquet utilise celles de votre application. La liste complète est dans peerDependencies de ui/package.json.

Ces composants servent aux applications Vue (frontend d'une application, portail, page sur mesure). Ils ne s'ajoutent pas aux formulaires et aux listes du bureau.

Intégrer le paquet

1. Déclarer la dépendance

Dans le package.json du frontend (par exemple apps/mon_app/frontend/package.json), pointez vers le dossier ui/ de l'application frappe du bench :

{
  "scripts": {
    "postinstall": "patch-package --patch-dir node_modules/@framework/ui/patches && patch-package"
  },
  "dependencies": {
    "@framework/ui": "link:../../frappe/ui"
  }
}

Adaptez le chemin relatif à l'emplacement de votre frontend. Le script postinstall applique les correctifs que le paquet livre pour ses dépendances (dossier ui/patches/, par exemple pour reka-ui).

2. Ajouter le plugin Vite

Le paquet est lié par un lien symbolique. Sans précaution, Vite chargerait une deuxième copie de vue ou de reka-ui. Le plugin force une seule copie :

// vite.config.js
import vue from "@vitejs/plugin-vue";
import frameworkUI from "@framework/ui/vite";

export default {
    plugins: [vue(), frameworkUI()],
};

Pour forcer aussi une seule copie d'un autre paquet : frameworkUI({ dedupe: ["mon-paquet"] }).

3. Importer les composants

import { Link } from "@framework/ui";
import { FormLayout } from "@framework/ui/FormLayout";

Contenu du paquet

ImportContenu
@framework/uiLink, FormLayout, Grid, Phone, TableMultiSelect, EmailComposer, CommentComposer, ActivityTimeline, Notifications, InviteUser, EmailAccounts, DataImportWizard, onboarding, bannières, télémétrie, aides temps réel (getSocketInstance, subscribeToDoc)
@framework/ui/FormLayoutFonctions et types complets de FormLayout : buildLayoutFromMeta, resolveLayout, CommitKey, NO_COMMIT…
@framework/ui/ActivityTimelineComposants de l'historique d'activité
@framework/ui/InviteUserInvitation d'utilisateurs
@framework/ui/EmailAccountsPanneau des comptes email : EmailAccounts, useEmailAccounts, useOneClick (voir plus bas)
@framework/ui/ListView, /Filter, /SortBy, /GroupBy, /QuickFilter, /ColumnSettings, /ConditionBuilderBriques des pages de liste
@framework/ui/experimental/ListListe expérimentale (List, ListFooter, ListBulkBar)
@framework/ui/FileUpload, /AutomationCanvas, /fields, /utilsEnvoi de fichiers, éditeur d'automatisations, champs, utilitaires
@framework/ui/island, /vite/islandÎles Vue

La racine exporte aussi les sous-composants de l'activité (TimelineContainer, CommentItem, EmailItem, LogItem, VersionItem, AttachmentChip, useActivityTimeline) et des notifications (NotificationPanel, NotificationItem, useNotifications).

Le sous-chemin @framework/ui/* donne accès à tout fichier de ui/src/. Le composable useDoctypeMeta, par exemple, n'est pas exporté par la racine : importez-le depuis @framework/ui/composables/useDoctypeMeta.

Exemple : formulaire construit depuis un DocType

Exemple fictif : une page Vue affiche un formulaire construit depuis les métadonnées du DocType ToDo.

<script setup lang="ts">
import { computed, provide, ref } from "vue";
import { FormLayout, buildLayoutFromMeta, CommitKey, NO_COMMIT } from "@framework/ui/FormLayout";
import { useDoctypeMeta } from "@framework/ui/composables/useDoctypeMeta";

const { meta } = useDoctypeMeta("ToDo");
const doc = ref({ description: "", priority: "Medium" });
const layout = computed(() => buildLayoutFromMeta(meta.value?.fields ?? []));

provide(CommitKey, NO_COMMIT);
</script>

<template>
    <FormLayout v-model:doc="doc" :layout="layout" />
</template>

provide(CommitKey, NO_COMMIT) indique que la page enregistre le document elle-même. Voir FormLayout.

Link est un champ de sélection d'un enregistrement d'un DocType, avec recherche.

<template>
    <Link
        v-model="customer"
        doctype="Customer"
        label="Client"
        :filters="{ disabled: 0 }"
        redirectable
    />
</template>

<script setup>
import { ref } from "vue";
import { Link } from "@framework/ui";

const customer = ref(null);
</script>
PropriétéRôle
doctypeDocType recherché. Obligatoire.
v-modelNom de l'enregistrement choisi, ou null.
filtersFiltres de la recherche.
creatableAjoute l'option « Create New ». Émet create avec le texte saisi.
redirectableAjoute un accès à l'enregistrement choisi. Émet redirect.
editableÉmet edit avec la valeur.
label, description, error, required, placeholder, disabledLibellé et état du champ.
titleTexte affiché pour la valeur avant la fin de la recherche.

Panneau des comptes email (EmailAccounts)

EmailAccounts est le panneau de réglage des comptes email d'un site, partagé par les applications : chaque application l'intègre au lieu d'écrire ses propres écrans. Helpdesk l'utilise dans ses réglages des comptes email. Le panneau lit et écrit le DocType Email Account par les méthodes de Frappe (frappe.client.*, email_oauth.initiate_mailbox_connect, etc.). L'application hôte ne fournit que ce qui lui est propre.

Le panneau liste les comptes sous forme de cartes (nom, adresse, interrupteurs de réception et d'envoi), propose les comptes entrant et sortant par défaut, permet d'ajouter un compte (mot de passe, clé d'API, serveurs IMAP/SMTP personnalisés ou connexion en un clic sur Frappe Cloud V2), de le modifier et de reconnecter une boîte dont la connexion a expiré. Pour Gmail, il demande d'abord l'adresse : une adresse @gmail.com ou @googlemail.com ouvre le formulaire avec un mot de passe d'application, une autre adresse affiche les étapes de l'administrateur Google Workspace puis ouvre la connexion Google avec cette adresse. Le côté utilisateur de ce parcours est décrit dans Configuration des emails.

<script setup lang="ts">
import { ref } from "vue";
import { EmailAccounts } from "@framework/ui/EmailAccounts";

const unsaved = ref(false);
</script>

<template>
    <EmailAccounts
        doctype="HD Ticket"
        v-model:dirty="unsaved"
        @created="(service) => console.log('Boîte ajoutée', service)"
    />
</template>
NomTypeRôle
doctypepropriétéDocType auquel le courrier entrant est ajouté. Obligatoire.
providerspropriétéValeurs de service des tuiles à proposer à l'ajout, par exemple ["GMail", "Outlook.com", ""] ("" : email personnalisé). Tous par défaut.
createdévénement(service) : une boîte a été ajoutée (mot de passe, clé d'API ou connexion en un clic). Une reconnexion ne l'émet pas.
dirtyv-modeltrue tant qu'un formulaire d'ajout ou de modification a des changements non enregistrés. L'hôte s'en sert pour protéger sa propre navigation.

Le panneau enregistre et recharge seul. Il remplit la hauteur de son conteneur (en-tête fixe, corps défilant) et n'ajoute aucune marge extérieure : montez-le dans un conteneur qui a une hauteur. Ses notifications et sa confirmation de modifications non enregistrées utilisent toast et dialog de frappe-ui : l'application doit monter FrappeUIProvider.

Retour d'une connexion en un clic

La connexion quitte la page et revient dessus avec ?email_oauth=<résultat>&email_oauth_mailbox=<adresse>&email_oauth_provider=<fournisseur>. Le panneau lit ces paramètres au montage et les retire de l'URL. L'hôte doit seulement ouvrir le panneau quand la page se charge avec email_oauth dans l'URL. connected et reconnected affichent une notification ; tout autre code affiche un message dans la liste. Pour une adresse Gmail ajoutée mais connectée avec un autre compte (wrong_mailbox), rien n'est ajouté et le panneau rouvre l'étape Gmail.

Les services proposés en un clic viennent de get_one_click_services, que le site met en cache 10 minutes. La liste est vide hors Frappe Cloud V2. Un service Google y est accompagné de son ID client, que l'administrateur Google Workspace autorise.

Afficher vos propres écrans

Pour présenter les comptes à votre façon, utilisez le composable sur lequel le panneau repose :

<script setup lang="ts">
import { onMounted } from "vue";
import { useEmailAccounts } from "@framework/ui/EmailAccounts";

const accounts = useEmailAccounts("HD Ticket");
onMounted(accounts.load);
</script>

<template>
    <MaRangee v-for="a in accounts.accounts" :key="a.name" :account="a" @reconnect="accounts.reconnect(a)" />
</template>

Le contrôleur renvoyé expose accounts, signIn, loading, error, load(), create(), update(), setDefault(), connect(service, email?), reconnect() et pull(). Avec email, connect demande au fournisseur de se connecter avec cette adresse, et une autre adresse n'est pas ajoutée. Quand la page revient d'une connexion, signIn contient le résultat et l'URL ne le contient plus ; une nouvelle boîte devient le compte par défaut là où il n'y en a pas. Afficher le résultat vous revient. useOneClick() renvoie les services connectables en un clic.

Salles temps réel d'un document (subscribeToDoc)

La racine exporte les aides de connexion temps réel que ActivityTimeline et useDataImport utilisent : getSocketInstance, subscribeToDoc et le type RealtimeSocket.

Côté serveur, doc_unsubscribe quitte simplement la salle du document. Si deux consommateurs écoutent le même document et que l'un d'eux quitte la salle, l'autre n'entend plus rien. subscribeToDoc évite ce cas : il tient un compteur de détenteurs par document et ne quitte la salle que lorsque le dernier détenteur la libère.

ExportRôle
getSocketInstance()Renvoie le socket de l'application, ou undefined s'il n'y en a pas. À appeler pendant setup() : hors d'un setup(), la fonction lève une erreur. Elle cherche le socket fourni par provide('socket', …) ou provide('$socket', …), puis dans les propriétés globales socket ou $socket de l'application. En mode développement, elle écrit un avertissement dans la console quand elle n'en trouve aucun.
subscribeToDoc(socket, doctype, docname)Rejoint la salle du document (événement doc_subscribe) pour le premier détenteur, et renvoie une fonction de libération. Sans socket (undefined), ne fait rien et renvoie une fonction vide.
RealtimeSocketType du socket attendu : emit(event, ...args), on(event, handler) et off(event, handler).

La fonction de libération est sans effet quand elle est appelée une deuxième fois. Quand le dernier détenteur d'un document la libère, doc_unsubscribe est émis. Après une reconnexion du socket (événement connect), les salles tenues sont rejointes de nouveau.

Le compteur de détenteurs est un état du module. Pour que votre application et ActivityTimeline partagent les mêmes salles, importez ces aides depuis @framework/ui : une copie du fichier dans votre application aurait son propre compteur et ne protégerait pas les salles de la frise d'activité.

Exemple fictif : un panneau d'une application affiche en direct les changements d'un ToDo et garde la salle ouverte tant qu'il est monté, même si une ActivityTimeline est affichée sur le même document.

<script setup lang="ts">
import { onBeforeUnmount } from "vue";
import { getSocketInstance, subscribeToDoc } from "@framework/ui";

const socket = getSocketInstance();
const leaveRoom = subscribeToDoc(socket, "ToDo", "T1");

onBeforeUnmount(leaveRoom);
</script>

Ajouter un composant partagé

Un composant entre dans @framework/ui seulement si plusieurs applications l'utilisent. Un composant propre à une application reste dans cette application.

  1. Créez ui/src/components/<Nom>/ avec le composant .vue, un index.ts et un types.ts.
  2. Exportez-le depuis ui/src/index.ts, ou ajoutez un sous-chemin dans ui/package.json (exports).