Bibliothèque de composants UI @framework/ui

Le dossier ui/ de Dodock contient le paquet @framework/ui. Ce sont des composants Vue 3 qui connaissent le backend Dodock : métadonnées des DocTypes, méthodes de l'API, notifications. Ils complètent frappe-ui, qui contient les composants génériques.

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

Prérequis

Le paquet déclare ces dépendances paires, à installer dans votre application : vue 3.3 ou plus, vue-router 4, frappe-ui et @vueuse/core.

Composants exportés par la racine

import { FormLayout, EmailComposer, Phone } from "@framework/ui";

Sous-chemins

Certains modules ont leur propre chemin. Il donne accès à toute leur API :

Contrôles de liste sur un portail : fournir les champs explicitement

Par défaut, les contrôles Filter, QuickFilter et SortBy déduisent les champs qu'ils proposent des métadonnées du DocType, récupérées avec useDoctypeMeta (méthode frappe.desk.form.load.getdoctype). Un utilisateur de portail n'a pas forcément accès à cette méthode du bureau.

Pour éviter cette requête, passez la propriété fieldOptions à ces trois contrôles. Dès que fieldOptions est définie, le contrôle ne demande aucune métadonnée et ne propose que les champs que vous fournissez.

Points à connaître :

• Une liste vide est une valeur explicite : le contrôle ne propose alors aucun champ, il ne revient pas aux métadonnées.
• Avec fieldOptions, les champs standard (name, owner, creation, modified…) ne sont pas ajoutés automatiquement. Déclarez ceux dont vous avez besoin.
• Le contrôle lit fieldOptions à son initialisation pour décider s'il charge les métadonnées. Gardez une source constante pour une instance du composant et remontez-le (par exemple avec :key) si vous changez de source.
• Ces options pilotent uniquement l'interface. Le serveur doit appliquer ses propres permissions sur les champs et sur les enregistrements.

Exemple fictif : une page de portail liste des factures de vente avec un filtre, des filtres rapides et un tri limités à trois champs.

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

const filters = ref([]);
const sort = ref([]);

const filterFields = [
  { label: "Date", fieldname: "posting_date", fieldtype: "Date" },
  { label: "Statut", fieldname: "status", fieldtype: "Select", options: "Paid\nUnpaid\nOverdue" },
  { label: "Client", fieldname: "customer", fieldtype: "Link", options: "Customer" },
];

const sortFields = [
  { label: "Date", fieldname: "posting_date" },
  { label: "Montant", fieldname: "grand_total" },
];
</script>

<template>
  <Filter v-model="filters" doctype="Sales Invoice" :field-options="filterFields" />
  <QuickFilter v-model:filters="filters" doctype="Sales Invoice" :field-options="filterFields" />
  <SortBy v-model="sort" doctype="Sales Invoice" :field-options="sortFields" />
</template>

Les libellés de cet exemple sont des valeurs d'illustration : adaptez-les à votre portail.

Exemple

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

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

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>

Pages liées

• Composant Composer
• Gestion des formulaires
• Personnalisation des onglets dans les formulaires
• Composants @framework/ui

Le fichier ui/README.md et les fichiers *.story.vue du dépôt Dodock montrent d'autres usages.