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.

Composants UI

Menus déroulants Espresso

Ajouter des éléments aux menus de l'en-tête d'un formulaire ou d'une page (menu •••, menu Actions, groupes de boutons) et comprendre leur comportement.

Menus déroulants Espresso

Les menus de l'en-tête d'un formulaire ou d'une page utilisent le composant frappe.ui.Dropdown. Cela concerne le menu •••, le menu Actions et les groupes de boutons personnalisés (« Créer », « Vue »…).

Vous ajoutez les éléments avec les méthodes de la page (frm.page ou page). La page garde les éléments dans une liste HTML masquée. À chaque ouverture, le menu relit cette liste. Une modification d'un élément (.text(), .toggle(), .addClass("disabled")) s'affiche donc à l'ouverture suivante.

Ajouter un élément au menu •••

frappe.ui.form.on("Customer", {
    refresh(frm) {
        frm.page.add_menu_item(__("Voir le relevé"), () => {
            frappe.set_route("query-report", "General Ledger", { party: frm.doc.name });
        });
    },
});

Signature : page.add_menu_item(label, click, standard, shortcut, show_parent).

Paramètre	Rôle
`label`	Libellé. Un libellé déjà présent n'est pas ajouté une deuxième fois.
`click`	Fonction appelée au clic.
`standard`	`true` place l'élément avec les éléments standard. Sinon, il va dans la zone des actions de l'utilisateur, en haut.
`shortcut`	Raccourci clavier, par exemple `"Ctrl+B"`. La page lie la touche et l'affiche dans le menu.
`show_parent`	`true` par défaut : affiche le bouton •••.

La méthode renvoie le lien jQuery de l'élément.

Ajouter un élément au menu Actions

frm.page.add_actions_menu_item(__("Exporter en PDF"), () => {
    frappe.call({
        method: "mon_app.api.export_pdf",
        args: { name: frm.doc.name },
    });
});

Signature : page.add_actions_menu_item(label, click, standard, shortcut, icon, theme). Passez theme: "red" pour une action destructive. page.add_action_item(label, click, standard, icon) existe aussi. Exemple fictif : mon_app.api.export_pdf est une méthode de votre application.

Créer un groupe de boutons

Passez le nom du groupe en troisième argument de frm.add_custom_button. Les boutons d'un même groupe forment un menu déroulant.

frappe.ui.form.on("Sales Order", {
    refresh(frm) {
        if (frm.doc.docstatus !== 1) return;
        frm.add_custom_button(__("Facture"), () => creer_facture(frm), __("Créer"));
        frm.add_custom_button(__("Bon de livraison"), () => creer_livraison(frm), __("Créer"));
    },
});

Pour retirer un bouton, appelez frm.remove_custom_button(label, group). frm.clear_custom_buttons() les retire tous.

Sur une page qui n'est pas un formulaire, page.add_inner_button(label, action, group) fait la même chose.

Comportement des menus

Clavier : flèches pour se déplacer, flèche droite et gauche pour les sous-menus, Entrée ou Espace pour choisir, Échap pour fermer et revenir au bouton.
Lettres Alt : maintenez Alt pour souligner une lettre par ligne. Alt + cette lettre choisit la ligne. Une ligne désactivée ou qui a un raccourci clavier n'a pas de lettre Alt.
Libellés : le libellé est affiché comme texte. Une balise HTML dans un libellé s'affiche telle quelle.
Téléphone : les boutons d'un groupe s'affichent dans le menu ••• sous la forme d'une ligne « Groupe » avec un sous-menu.

Résoudre un problème

Problème	Cause probable
L'élément n'apparaît pas	Un élément avec le même libellé existe déjà dans ce menu.
Le bouton reste après un changement d'état	Le script ajoute le bouton dans `refresh` sans condition. Testez l'état du document avant `add_custom_button`.
Le raccourci ne fonctionne pas	Le raccourci est passé dans une option `shortcut` d'un élément `frappe.ui.Dropdown`. Cette option sert à l'affichage seul : liez la touche avec `frappe.ui.keys.add_shortcut`.