Composants UI Espresso

Espresso est le système de composants du desk. Chaque composant est une fonction de frappe.ui. Le code se trouve dans frappe/public/js/frappe/ui/components/.

La plupart des composants existent sous deux formes :

Les icônes sont des noms d'icônes Lucide : "check", "trash-2", "printer". Les libellés sont affichés comme texte, jamais comme HTML : traduisez-les avec __() avant de les passer.

L'Explorateur de composants montre chaque composant avec des exemples.

D'autres composants Espresso ont leur propre page : Stepper, Sections optionnelles, Groupe d'avatars, Skeleton et Divider, Menus déroulants et Info-bulles intelligentes.

Les composants Vue des applications (paquet @framework/ui, construit sur frappe-ui) sont décrits à part : voir Package @framework/ui.

Bouton : frappe.ui.button

const $btn = frappe.ui.button({
    label: __("Save"),
    variant: "solid",
    icon: "check",
    onclick: () => frm.save(),
});
$btn.appendTo(frm.fields_dict.actions_html.$wrapper);

Si onclick renvoie une promesse, le bouton affiche un indicateur de chargement jusqu'à la fin de la promesse.

frappe.ui.button.dress(el, opts) applique le style Espresso à un bouton qui existe déjà.

Badge : frappe.ui.badge

frappe.ui.badge({ label: __("Overdue"), theme: "red" }).appendTo($row);

Menu déroulant : frappe.ui.Dropdown

Le menu s'ouvre sur un élément déclencheur. Il remplace l'attribut Bootstrap data-toggle="dropdown".

new frappe.ui.Dropdown({
    trigger: $(".menu-btn"),
    options: [
        { label: __("Edit"), icon: "pen", onclick: () => edit() },
        { label: __("Delete"), icon: "trash", theme: "red", onclick: () => remove() },
    ],
});

La forme courte frappe.ui.dropdown(opts) crée aussi le bouton déclencheur et le renvoie. L'instance est dans .data("es-dropdown").

page.body.append(
    frappe.ui.dropdown({
        button: { label: __("Actions") },
        options: [{ label: __("Duplicate"), onclick: () => duplicate() }],
    })
);

Méthodes de l'instance : open(), close(), toggle(), set_options(options), destroy().

Éléments de menu

Pour un groupe, passez { group: "Titre", hide_label: false, options: [...] }.

Le clavier fonctionne dans tous les menus : flèches pour se déplacer, droite et gauche pour les sous-menus, Entrée ou Espace pour choisir, Échap pour fermer. Une lettre saisie va à la ligne qui commence par cette lettre. Maintenir Alt souligne une lettre par ligne : Alt + cette lettre choisit la ligne.

Menu contextuel : frappe.ui.ContextMenu

Le menu s'ouvre au clic droit sur un élément, à la position du pointeur. Il accepte les mêmes éléments que frappe.ui.Dropdown.

new frappe.ui.ContextMenu({
    target: row_el,
    options: () => [
        { label: __("Open"), icon: "external-link", onclick: () => open_row() },
        { label: __("Delete"), icon: "trash-2", theme: "red", onclick: () => delete_row() },
    ],
});

Pendant l'ouverture, la cible porte l'attribut data-state="open". Utilisez-le pour mettre en évidence la ligne concernée.

Notification : frappe.ui.toast

frappe.ui.toast({ message: __("Saved"), type: "success" });

frappe.ui.toast.promise(frm.save(), {
    loading: __("Saving..."),
    success: __("Saved"),
});

frappe.ui.toast() renvoie { id, $el, dismiss, update }.

Panneau inférieur : frappe.ui.BottomSheet

Le panneau inférieur monte depuis le bas de l'écran. Il sert aux choix, aux formulaires courts et aux confirmations sur téléphone. La page derrière est assombrie et le focus reste dans le panneau jusqu'à sa fermeture.

Le composant ne fait pas partie des bundles du desk. Chargez son script et ses styles avant la première utilisation :

await frappe.require(["bottom_sheet.bundle.js", "bottom_sheet.bundle.css"]);

new frappe.ui.BottomSheet({
    title: __("Sort by"),
    options: [{ label: __("Created On"), selected: true, onclick: () => sort("creation") }],
}).open();

La forme courte frappe.ui.bottom_sheet(opts) crée un bouton déclencheur (option button) et le renvoie, sans ouvrir le panneau. Ajoutez ce bouton dans la page. L'instance est dans .data("es-bottom-sheet").

toolbar.append(
    frappe.ui.bottom_sheet({
        button: { label: __("Sort"), icon: "arrow-down-wide-narrow" },
        title: __("Sort by"),
        options: sort_options,
    })
);

Options d'une étape :

Options du panneau :

Méthodes : open(), close(reason), toggle(), push(step) (ajoute une étape et affiche le bouton Retour), pop(), set_title(title, subtitle), set_options(options) et set_height(height). Un choix qui en appelle un autre est une étape ajoutée avec push(), pas un deuxième panneau. Un changement de page ferme le panneau.

Info-bulle : frappe.ui.tooltip

frappe.ui.tooltip($btn, { text: __("Refresh"), shortcut: "ctrl+r" });

Les options principales sont text, side, align, delay (500 ms par défaut), shortcut et only_on_overflow. Voir Info-bulles intelligentes.

Personnaliser les styles

Les composants portent des classes es-* (es-button, es-badge, es-avatar-group…) et des attributs data-variant, data-size, data-theme. Les styles se trouvent dans frappe/public/css/espresso/. Pour adapter un composant, ciblez ces classes et attributs dans le CSS de votre application.

.es-button[data-variant="solid"] {
    font-weight: 600;
}