Bibliothèque de composants UI @framework/ui

Dodock v5 intègre désormais la bibliothèque de composants UI @framework/ui, backportée depuis la branche develop de Frappe. Cette bibliothèque offre aux développeurs et administrateurs un ensemble de composants Vue.js réutilisables pour personnaliser et enrichir l'interface utilisateur de Dokos.

Composants disponibles

La bibliothèque @framework/ui inclut les composants suivants, conçus pour être utilisés dans des applications personnalisées ou des extensions de l'interface :

Composants de formulaire

FormLayout

Un rendu de formulaire piloté par schéma, supportant les grilles, les téléversements de fichiers et les éditeurs de code.

Cas d'usage :

• Création de formulaires dynamiques sans écrire de HTML personnalisé.
• Intégration de champs complexes comme les éditeurs de code ou les téléversements de fichiers.

Exemple d'utilisation :

import { FormLayout } from '@framework/ui';

// Définir un schéma de formulaire
const schema = {
  fields: [
    {
      fieldtype: 'Data',
      fieldname: 'customer_name',
      label: 'Nom du client',
      reqd: 1
    },
    {
      fieldtype: 'Attach',
      fieldname: 'attachment',
      label: 'Pièce jointe'
    }
  ]
};

// Rendre le formulaire dans un dialogue
const dialog = new frappe.ui.Dialog({
  title: 'Nouveau client',
  size: 'large'
});

dialog.body.appendChild(FormLayout.render(schema));
dialog.show();

PhoneInput

Un champ de saisie pour les numéros de téléphone avec validation automatique des indicatifs internationaux.

Cas d'usage :

• Saisie de numéros de téléphone pour les fiches clients ou fournisseurs.
• Validation des numéros en fonction du pays sélectionné.

Exemple d'utilisation :

import { PhoneInput } from '@framework/ui';

// Ajouter un champ PhoneInput à un formulaire
const phoneField = PhoneInput.create({
  label: 'Téléphone',
  fieldname: 'phone',
  country: 'FR' // Indicatif par défaut
});

frm.add_custom_field(phoneField);

Composants de notification

Notifications

Un panneau de notifications extensible, permettant de filtrer les notifications par application et par type.

Cas d'usage :

• Centralisation des notifications pour les utilisateurs.
• Filtrage des notifications par application (ex. : Dokos, CRM, Helpdesk).

Configuration : Les notifications sont gérées via les doctypes Notification Type et Notification Type Preference, permettant de définir des types de notifications personnalisés et de configurer les préférences d'envoi (email, popup, etc.).

Composants de liste et tableau de bord

ActivityTimeline

Un composant affichant une timeline des activités liées à un document (emails, commentaires, modifications).

Cas d'usage :

• Visualisation de l'historique des interactions avec un client ou un fournisseur.
• Suivi des modifications apportées à un document.

Exemple d'utilisation :

import { ActivityTimeline } from '@framework/ui';

// Récupérer les activités pour un document
frappe.call({
  method: 'frappe.desk.form.activity.get_activity_timeline',
  args: {
    doctype: 'Customer',
    docname: 'Maison Verte SARL'
  },
  callback: function(r) {
    if (r.message) {
      // Afficher la timeline dans un conteneur
      const timeline = ActivityTimeline.create(r.message);
      $('.timeline-container').append(timeline);
    }
  }
});

ListViewControls

Un ensemble de contrôles pour personnaliser les vues liste (filtres, colonnes, paramètres).

Cas d'usage :

• Ajout de colonnes synthétiques dans les vues liste.
• Personnalisation des paramètres de colonne (largeur, ordre).

Exemple d'utilisation :

import { ListViewControls } from '@framework/ui';

// Ajouter une colonne synthétique à une vue liste
frappe.listview_settings['Sales Invoice'] = {
  onload: function(listview) {
    const controls = ListViewControls.create(listview);
    controls.addSyntheticColumn({
      label: 'Montant dû',
      fieldname: 'outstanding_amount',
      fieldtype: 'Currency'
    });
  }
};

Composants de composition

Composer

Un composant pour rédiger des emails ou des commentaires avec une interface riche.

Cas d'usage :

• Rédaction d'emails directement depuis un document (ex. : fiche client).
• Ajout de commentaires avec mise en forme.

Exemple d'utilisation :

import { Composer } from '@framework/ui';

// Ouvrir un compositeur d'email
const composer = Composer.create({
  doctype: 'Customer',
  docname: 'Maison Verte SARL',
  type: 'email',
  subject: 'Suivi de votre commande'
});

composer.show();

Configuration des types de notifications

La bibliothèque @framework/ui introduit des doctypes pour gérer les types de notifications et leurs préférences :

Notification Type

Ce doctype permet de définir des types de notifications personnalisés, avec les champs suivants :

Notification Type Preference

Ce doctype permet de configurer les préférences d'envoi pour chaque type de notification :

Notification Log

Ce doctype stocke les notifications envoyées aux utilisateurs, avec les champs suivants :

Personnalisation de l'interface avec @framework/ui

Ajouter un composant à un formulaire personnalisé

1. Importer le composant :

   import { FormLayout } from '@framework/ui';
   

2. Définir un schéma :

   const schema = {
     fields: [
       {
         fieldtype: 'Data',
         fieldname: 'customer_name',
         label: 'Nom du client'
       }
     ]
   };
   

3. Rendre le composant :

   const form = FormLayout.render(schema);
   $('.form-container').append(form);
   

Intégrer un composant dans une vue liste

1. Importer le composant :

   import { ListViewControls } from '@framework/ui';
   

2. Configurer la vue liste :

   frappe.listview_settings['Sales Invoice'] = {
     onload: function(listview) {
       const controls = ListViewControls.create(listview);
       controls.addSyntheticColumn({
         label: 'Montant dû',
         fieldname: 'outstanding_amount',
         fieldtype: 'Currency'
       });
     }
   };
   

Bonnes pratiques

• Réutilisabilité : Les composants @framework/ui sont conçus pour être réutilisés dans plusieurs applications. Évitez de dupliquer du code en les intégrant dans vos personnalisations.
• Performance : Les composants sont optimisés pour minimiser les temps de chargement. Utilisez-les avec parcimonie dans les vues liste ou les formulaires fréquemment utilisés.
• Compatibilité : Les composants sont compatibles avec les versions récentes de Vue.js (v3). Assurez-vous que vos personnalisations utilisent une version compatible.
• Documentation : Consultez la documentation officielle de Frappe pour des exemples supplémentaires et des mises à jour sur les composants disponibles.

Exemple complet : Ajouter une timeline d'activités à la fiche client

Objectif : Afficher une timeline des activités (emails, commentaires) sur la fiche client.

1. Créer un script personnalisé pour le DocType Customer :

   // customer.js
   frappe.ui.form.on('Customer', {
     refresh: function(frm) {
       // Importer le composant ActivityTimeline
       import('@framework/ui').then(({ ActivityTimeline }) => {
         // Récupérer les activités
         frappe.call({
           method: 'frappe.desk.form.activity.get_activity_timeline',
           args: {
             doctype: 'Customer',
             docname: frm.doc.name
           },
           callback: function(r) {
             if (r.message) {
               // Créer et afficher la timeline
               const timeline = ActivityTimeline.create(r.message);
               frm.add_custom_section('activity_timeline', 'Timeline des activités');
               frm.fields_dict['activity_timeline'].$wrapper.append(timeline);
             }
           }
         });
       });
     }
   });
   

2. Ajouter le script au DocType :
   • Allez dans Personnaliser le formulaire > Customer.
   • Ajoutez le chemin vers le script dans le champ Script personnalisé.
3. Résultat :
   • La fiche client affiche désormais une section Timeline des activités avec l'historique des interactions.

Limitations et contraintes

• Compatibilité : Les composants @framework/ui sont conçus pour Dodock v5 et versions ultérieures. Ils ne sont pas compatibles avec les versions antérieures.
• Personnalisation : Certains composants peuvent nécessiter des ajustements pour s'intégrer parfaitement à des interfaces personnalisées.
• Documentation : La documentation complète des composants est disponible dans le dépôt Frappe. Consultez les fichiers .md dans le dossier ui/ pour des détails supplémentaires.

Ressources supplémentaires

• Documentation officielle de Frappe UI
• Exemples de composants
• Guide de contribution