Interface utilisateur

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

Dokos introduit une nouvelle boîte de dialogue des paramètres (frappe.ui.SettingsDialog) qui permet de regrouper et d'organiser les options de configuration de manière intuitive. Cette fonctionnalité est particulièrement utile pour les modules nécessitant plusieurs sections de configuration.

Fonctionnement

La boîte de dialogue des paramètres se présente sous la forme d'un panneau latéral avec deux sections principales :

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

      
flowchart LR
    A[Rail de navigation] -->|Sélection| B[Panneau principal]
    B -->|Actions| C[Sauvegarde/Annulation]

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'),
        primary: true,
        click(panel) {
          const values = panel.get_values();
          // Logique de sauvegarde
        }
      }]
    }]
  }]
}).show();

Contrôle Switch

Le contrôle Switch (fieldtype: "Switch") est un nouvel élément d'interface qui permet d'activer ou de désactiver une option de manière visuelle. Il est utilisable dans n'importe quel formulaire ou boîte de dialogue.

Exemple d'utilisation

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

Comportement

Cliquer n'importe où sur la ligne active/désactive le switch.
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éthode	Description
`panel.get_values()`	Récupère les valeurs du formulaire
`panel.set_values(values)`	Définit les valeurs du formulaire
`panel.refresh()`	Réinitialise le panneau à sa vue par défaut
`panel.set_header(title, description)`	Met à jour le titre et la description

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'),
            primary: true,
            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

Regroupez les options logiquement : Utilisez les groupes et onglets pour organiser les paramètres par thème.
Utilisez des descriptions claires : Chaque onglet doit avoir une description qui explique son utilité.
Limitez le nombre d'actions : Privilégiez une action principale (ex: "Sauvegarder") et évitez les actions secondaires inutiles.
Testez la navigation : Assurez-vous que le passage d'un onglet à l'autre fonctionne sans perte de données.
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.

::: tip Pour les développeurs, ces primitives sont réutilisables dans n'importe quel module Dokos. Consultez la documentation technique pour plus de détails sur l'API. :::