Interface

Boîte de dialogue des paramètres

Utilisez la boîte de dialogue des paramètres pour configurer des options groupées dans Dokos

Boîte de dialogue des paramètres

frappe.ui.SettingsDialog affiche des paramètres regroupés en onglets, dans une grande boîte de dialogue. Utilisez-la pour un module qui a plusieurs sections de configuration.

Fonctionnement

SettingsDialog hérite de frappe.ui.Dialog (taille extra-large par défaut). Elle a deux zones :

  1. Rail de navigation vertical : Liste les groupes et onglets disponibles.
  2. Panneau principal : Affiche le contenu de l'onglet sélectionné, avec des champs de formulaire, des descriptions et des actions.

Utilisation de base

Pour ouvrir une boîte de dialogue des paramètres, utilisez le code suivant :

new frappe.ui.SettingsDialog({
  title: __('Paramètres'),
  default_tab: "preferences",
  tabs: [{
    group: __('Configuration'),
    items: [{
      id: "preferences",
      label: __('Préférences'),
      icon: "sliders-vertical",
      title: __('Préférences'),
      description: __('Gérez vos préférences'),
      fields: [
        {
          label: __('Thème sombre'),
          fieldname: "dark_mode",
          fieldtype: "Switch"
        }
      ],
      actions: [{
        label: __('Sauvegarder'),
        variant: "solid",
        click(panel) {
          const values = panel.get_values();
          // Logique de sauvegarde
        }
      }]
    }]
  }]
}).show();

Contrôle Switch

Le contrôle Switch (fieldtype: "Switch") affiche un interrupteur. Il reprend le contrôle Check (mêmes valeurs 0 et 1) avec une autre apparence. Il fonctionne dans un FieldGroup, une boîte de dialogue ou un formulaire.

Exemple d'utilisation

{
  label: __('Activer la fonctionnalité'),
  fieldname: "enable_feature",
  fieldtype: "Switch",
  default: 1
}

Comportement

  • Un clic sur le libellé bascule l'interrupteur.
  • La valeur renvoyée par get_values() est 1 (activé) ou 0 (désactivé).
  • Compatible avec les validations de champ (obligatoire, lecture seule, etc.).

Personnalisation avancée

Panneaux dynamiques

Chaque panneau (SettingsDialogPanel) peut être mis à jour dynamiquement avec panel.set_view() :

panel.set_view({
  title: __('Nouveau titre'),
  description: __('Nouvelle description'),
  fields: [ /* nouveaux champs */ ],
  actions: [ /* nouvelles actions */ ]
});

Méthodes utiles

MéthodeDescription
panel.get_values()Renvoie les valeurs des champs, ou null si un champ obligatoire est vide
panel.get_value(fieldname)Renvoie la valeur d'un champ
panel.set_values(values)Remplit les champs (renvoie une Promise)
panel.refresh()Réinitialise le panneau à sa vue par défaut
panel.set_header({ title, description, actions })Met à jour l'en-tête seul
panel.bodyConteneur jQuery du contenu, pour une fonction render(panel)

Exemple complet

Voici un exemple complet de configuration pour un module de gestion des notifications :

new frappe.ui.SettingsDialog({
  title: __('Paramètres des notifications'),
  default_tab: "email",
  tabs: [{
    group: __('Canaux'),
    items: [
      {
        id: "email",
        label: __('Email'),
        icon: "envelope",
        title: __('Notifications par email'),
        description: __('Configurez les notifications envoyées par email'),
        fields: [
          {
            label: __('Activer les emails'),
            fieldname: "enable_emails",
            fieldtype: "Switch",
            default: 1
          },
          {
            label: __('Fréquence'),
            fieldname: "email_frequency",
            fieldtype: "Select",
            options: ["Immédiat", "Quotidien", "Hebdomadaire"],
            depends_on: "eval:doc.enable_emails"
          }
        ],
        actions: [
          {
            label: __('Sauvegarder'),
            variant: "solid",
            click(panel) {
              const values = panel.get_values();
              frappe.call({
                method: "module.api.save_settings",
                args: { values },
                callback: () => {
                  frappe.show_alert({
                    message: __('Paramètres sauvegardés'),
                    indicator: 'green'
                  });
                }
              });
            }
          }
        ]
      }
    ]
  }]
}).show();

Bonnes pratiques

Une action n'a pas de clé primary. Pour l'action principale, passez variant: "solid". Les autres clés d'une action sont label, icon, theme, class et click(panel).
  1. Regroupez les options logiquement : Utilisez les groupes et onglets pour organiser les paramètres par thème.
  2. Utilisez des descriptions claires : Chaque onglet doit avoir une description qui explique son utilité.
  3. Limitez le nombre d'actions : Privilégiez une action principale (ex: "Sauvegarder") et évitez les actions secondaires inutiles.
  4. Testez la navigation : Assurez-vous que le passage d'un onglet à l'autre fonctionne sans perte de données.
  5. Utilisez le contrôle Switch pour les options binaires : Il offre une meilleure expérience utilisateur que les cases à cocher classiques.

Cas d'usage

  • Configuration des préférences utilisateur : Thème, langue, fuseau horaire.
  • Paramètres de module : Notifications, intégrations, options de synchronisation.
  • Tableaux de bord personnalisables : Choix des widgets à afficher.
Les exemples passent des textes français à __() pour la lisibilité. Dans une application, écrivez les textes source en anglais (__("Settings")) et traduisez-les dans le fichier de traduction de l'application.