--- title: "Utiliser les composants d'interface" description: "Guide pour intégrer et personnaliser les composants UI standard dans Dokos" icon: i-mdi-puzzle ---

Utiliser les composants d'interface

Dokos fournit des composants d'interface standardisés pour simplifier le développement et garantir une expérience utilisateur cohérente. Ces composants sont accessibles via des helpers JavaScript et peuvent être utilisés dans les formulaires, les listes et les dialogues.

Boutons standardisés avec frappe.ui.button

Le helper frappe.ui.button permet de créer des boutons au style Espresso de manière programmatique, sans avoir à écrire manuellement le balisage HTML. Ce helper gère automatiquement :

• Les états de chargement (aria-busy)
• L'échappement des labels et attributs pour la sécurité
• Le rendu des icônes via frappe.utils.icon
• La cohérence des styles et des comportements

Utilisation de base

Variante jQuery (élément interactif)

const button = frappe.ui.button({
  label: "Enregistrer",
  variant: "primary",
  onclick: () => {
    return frappe.call({
      method: "ma_methode",
      args: { docname: cur_frm.doc.name }
    }).then(r => {
      frappe.show_alert({ message: "Enregistré !", indicator: "green" });
    });
  }
});

// Ajouter au DOM
$(document.body).append(button);

Variante HTML (pour les templates)

const buttonHtml = frappe.ui.button.html({
  label: "Annuler",
  variant: "secondary",
  icon: "i-mdi-close"
});

// Utiliser dans un template
const template = `
  <div class="form-actions">
    ${buttonHtml}
  </div>
`;

Options disponibles

Exemples concrets

Bouton avec état de chargement

frappe.ui.button({
  label: "Traiter les commandes",
  variant: "primary",
  onclick: () => {
    return new Promise(resolve => {
      setTimeout(() => {
        frappe.show_alert("Traitement terminé !");
        resolve();
      }, 2000);
    });
  }
});

Bouton icône avec infobulle

frappe.ui.button({
  icon: "i-mdi-printer",
  variant: "tertiary",
  title: "Imprimer le document",
  onclick: () => window.print()
});

Bouton dans un dialogue

const d = new frappe.ui.Dialog({
  title: "Confirmation",
  fields: [
    { fieldtype: "HTML", fieldname: "message", options: "Voulez-vous vraiment supprimer ?" }
  ]
});

d.add_button(frappe.ui.button({
  label: "Supprimer",
  variant: "danger",
  onclick: () => {
    // Logique de suppression
    d.hide();
  }
}));

Bonnes pratiques

1. Accessibilité :
   • Toujours fournir un title pour les boutons icône
   • Utiliser des labels clairs et concis
2. Sécurité :
   • Le helper échappe automatiquement les labels et attributs
   • Ne jamais utiliser d'attributs on* (utiliser onclick à la place)
3. Cohérence :
   • Privilégier les variantes standard (primary, secondary) pour les actions principales
   • Utiliser danger uniquement pour les actions irréversibles
4. Performance :
   • Pour les listes ou tableaux, générer le HTML via frappe.ui.button.html() puis injecter en une seule opération

Migration depuis les anciens boutons

Remplacez les balises <button> ou <a class="btn"> existantes par le helper :

Avant :

<button class="btn btn-primary" onclick="soumettre()">
  <i class="octicon octicon-check"></i> Soumettre
</button>

Après :

frappe.ui.button({
  label: "Soumettre",
  variant: "primary",
  icon: "i-mdi-check",
  onclick: soumettre
});

Autres composants UI

Dokos fournit également d'autres helpers pour les composants courants :

• Badges : frappe.ui.badge()
• Alertes : frappe.show_alert()
• Dialogues : frappe.ui.Dialog
• Listes embarquées : frappe.ui.EmbeddedList

Pour plus de détails sur ces composants, consultez la documentation technique de Frappe.

::: tip Bon à savoir Les composants Espresso sont conçus pour s'adapter automatiquement au thème clair/sombre de Dokos. :::