Documentation
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.
Personnalisation

Icônes personnalisées

Dokos permet désormais aux applications et aux administrateurs de fournir leurs propres icônes SVG pour enrichir l'interface utilisateur. Ces icônes personnalisées peuvent être utilisées sur les types de documents, les boutons, les tableaux de bord et d'autres composants de l'interface, offrant une flexibilité accrue pour adapter l'apparence de Dokos à l'identité visuelle de votre organisation.

Icônes personnalisées

Dokos permet désormais aux applications et aux administrateurs de fournir leurs propres icônes SVG pour enrichir l'interface utilisateur. Ces icônes personnalisées peuvent être utilisées sur les types de documents, les boutons, les tableaux de bord et d'autres composants de l'interface, offrant une flexibilité accrue pour adapter l'apparence de Dokos à l'identité visuelle de votre organisation.

Pourquoi utiliser des icônes personnalisées ?

  • Identité visuelle : Utilisez des icônes qui reflètent l'identité de votre entreprise ou de votre secteur d'activité.
  • Clarté : Des icônes spécifiques aident les utilisateurs à identifier rapidement les types de documents ou les actions associées.
  • Flexibilité : Ajoutez des icônes pour des types de documents personnalisés ou des fonctionnalités spécifiques à votre organisation.
  • Cohérence : Maintenez une cohérence visuelle entre Dokos et d'autres outils utilisés par votre équipe.

Prérequis

  • Permissions : Seuls les utilisateurs avec les permissions d'administrateur peuvent créer et gérer des icônes personnalisées.
  • Format SVG : Les icônes doivent être fournies au format SVG. Dokos nettoie automatiquement le code pour des raisons de sécurité.

Créer une icône personnalisée

Depuis l'interface utilisateur

  1. Allez dans Recherche globale (⌘K / Ctrl+K) et tapez "Icône personnalisée".
  2. Cliquez sur Nouveau pour créer une nouvelle icône.
  3. Remplissez les champs suivants :
    • Nom de l'icône : Un identifiant unique pour l'icône (ex. : ma-societe-logo). Utilisez des lettres minuscules, des chiffres et des tirets pour éviter les conflits.
    • SVG : Collez le code SVG de votre icône. Attention : Le code doit être un seul élément <svg> sans scripts ni gestionnaires d'événements. Dokos nettoie automatiquement le code pour supprimer les éléments potentiellement dangereux.
  4. Cliquez sur Enregistrer.

Exemple — Maison Verte SARL Maison Verte SARL souhaite utiliser une icône personnalisée pour son type de document "Projet client". L'administrateur crée une icône nommée maison-verte-projet et colle le code SVG suivant :

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
  <path fill="currentColor" d="M12 2L4 12l8 10 8-10z"/>
</svg>

Après enregistrement, cette icône est disponible dans le sélecteur d'icônes pour les types de documents.

Depuis une application Dokos

Les applications Dokos peuvent fournir leurs propres icônes personnalisées en incluant des fichiers SVG dans le dossier icons de l'application. Ces icônes sont automatiquement enregistrées lors de l'installation ou de la mise à jour de l'application.

Structure du dossier :

mon_application/
├── icons/
│   ├── icone1.svg
│   ├── icone2.svg
│   └── ...
├── hooks.py
└── ...

Configuration dans hooks.py :

# hooks.py
def get_hooks():
    return {
        "custom_icons": [
            "mon_application/icons/icone1.svg",
            "mon_application/icons/icone2.svg",
        ]
    }

Bon à savoir :

  • Les icônes fournies par une application sont disponibles pour tous les sites où l'application est installée.
  • Le nom de l'icône est dérivé du nom du fichier SVG (ex. : icone1.svg → icone1).
  • Si une icône fournie par une application porte le même nom qu'une icône existante (Lucide ou personnalisée), l'icône de l'application sera prioritaire.

Utiliser une icône personnalisée

Sur un type de document

  1. Allez dans Personnaliser le formulaire (recherche globale) et sélectionnez le type de document concerné.
  2. Dans le champ Icône, cliquez sur l'icône de recherche (loupe).
  3. Dans le sélecteur d'icônes, allez dans la section Personnalisé et sélectionnez votre icône.
  4. Cliquez sur Mettre à jour pour enregistrer le type de document.

Exemple — Bureau Moderne Bureau Moderne utilise un type de document personnalisé "Contrat fournisseur". L'administrateur attribue l'icône contrat (créée précédemment) à ce type de document. Désormais, tous les liens vers les contrats fournisseurs dans l'interface affichent cette icône, facilitant leur identification visuelle.

Dans un script client

Les icônes personnalisées peuvent également être utilisées dans des scripts clients pour personnaliser des boutons ou des éléments d'interface.

Exemple — Ajouter un bouton avec une icône personnalisée :

// Dans un script client
frappe.ui.form.on("Sales Order", {
    refresh(frm) {
        frm.add_custom_button(__("Envoyer au fournisseur"), function() {
            // Logique du bouton
        }).addClass("btn-primary").prepend(
            frappe.utils.icon("ma-societe-envoyer", "md")
        );
    }
});

Gérer les icônes personnalisées

Modifier une icône

  1. Allez dans Recherche globale et tapez "Icône personnalisée".
  2. Sélectionnez l'icône à modifier.
  3. Modifiez le champ SVG avec le nouveau code.
  4. Cliquez sur Enregistrer.

Bon à savoir : Les modifications apportées à une icône sont immédiatement visibles dans toute l'interface, y compris sur les types de documents qui l'utilisent.

Supprimer une icône

  1. Allez dans Recherche globale et tapez "Icône personnalisée".
  2. Sélectionnez l'icône à supprimer.
  3. Cliquez sur Supprimer.

Attention :

  • La suppression d'une icône est définitive.
  • Si l'icône est utilisée sur un type de document, elle sera remplacée par l'icône par défaut du type de document.
  • Les icônes fournies par une application ne peuvent pas être supprimées via l'interface. Pour les supprimer, désinstallez ou mettez à jour l'application.

Sécurité et bonnes pratiques

Sécurité

  • Nettoyage automatique : Dokos nettoie automatiquement le code SVG pour supprimer les scripts, gestionnaires d'événements, éléments HTML et autres contenus potentiellement dangereux. Ne tentez pas de contourner cette protection.
  • Validation : Seuls les éléments <svg> uniques et valides sont acceptés. Les icônes contenant plusieurs éléments ou des balises non autorisées seront rejetées.
  • Permissions : Seuls les administrateurs peuvent créer, modifier ou supprimer des icônes personnalisées.

Bonnes pratiques

  • Nommage : Utilisez des noms d'icônes clairs et uniques pour éviter les conflits avec les icônes Lucide ou celles d'autres applications. Privilégiez les noms en minuscules avec des tirets (ex. : ma-societe-logo).
  • Taille : Les icônes SVG doivent être conçues pour une taille de 24x24 pixels. Utilisez l'attribut viewBox="0 0 24 24" pour garantir un rendu optimal.
  • Couleur : Utilisez fill="currentColor" pour que l'icône hérite de la couleur du texte environnant. Cela permet une intégration harmonieuse avec le thème de Dokos.
  • Performance : Les icônes personnalisées sont chargées dans le sprite SVG du bureau, ce qui garantit des performances optimales. Évitez les icônes trop complexes pour ne pas alourdir le sprite.
  • Compatibilité : Testez vos icônes sur différents navigateurs pour garantir un rendu cohérent.

Exemple de code SVG optimisé

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
  <path fill="currentColor" d="M12 2L4 12l8 10 8-10z"/>
</svg>

Points clés :

  • xmlns : Déclare l'espace de noms SVG.
  • viewBox="0 0 24 24" : Définit la zone de dessin.
  • width="24" height="24" : Définit la taille par défaut.
  • fill="currentColor" : Permet à l'icône d'hériter de la couleur du texte.

Résoudre les problèmes courants

L'icône ne s'affiche pas

  • Vérifiez le nom : Assurez-vous que le nom de l'icône est correctement saisi dans le champ Icône du type de document.
  • Vérifiez le code SVG : Le code doit être un seul élément <svg> valide. Utilisez un validateur SVG en ligne pour vérifier votre code.
  • Videz le cache : Parfois, le sprite SVG du bureau est mis en cache. Essayez de vider le cache de votre navigateur ou de recharger la page avec Ctrl+F5 (Windows) ou Cmd+Shift+R (Mac).
  • Vérifiez les conflits : Si une icône personnalisée porte le même nom qu'une icône Lucide, l'icône personnalisée doit être prioritaire. Si ce n'est pas le cas, renommez votre icône.

L'icône est déformée

  • Vérifiez le viewBox : Assurez-vous que l'attribut viewBox est correctement défini (ex. : viewBox="0 0 24 24").
  • Vérifiez les proportions : Les icônes doivent être conçues pour une taille carrée (24x24 pixels). Si votre icône est rectangulaire, ajustez le viewBox ou redessinez l'icône.
  • Testez dans différents navigateurs : Certains navigateurs peuvent interpréter le SVG différemment. Testez votre icône sur Chrome, Firefox et Edge.

Le sélecteur d'icônes ne montre pas la section "Personnalisé"

  • Vérifiez les permissions : Seuls les administrateurs peuvent voir la section "Personnalisé" dans le sélecteur d'icônes.
  • Vérifiez les icônes existantes : Si aucune icône personnalisée n'existe sur le site, la section "Personnalisé" ne s'affiche pas.
  • Redémarrez le bureau : Parfois, le bureau doit être rechargé pour prendre en compte les nouvelles icônes. Essayez de vous déconnecter et de vous reconnecter.

Cas d'usage avancés

Utiliser des icônes personnalisées dans un format d'impression

Les icônes personnalisées peuvent être intégrées dans les formats d'impression pour ajouter une touche visuelle à vos documents.

Exemple — Ajouter une icône dans un format d'impression :

<!-- Dans un format d'impression personnalisé -->
<div class="header">
  <div class="logo">
    {{ frappe.utils.icon("ma-societe-logo", "lg") }}
  </div>
  <h1>{{ doc.name }}</h1>
</div>

Utiliser des icônes personnalisées dans un script serveur

Les icônes personnalisées peuvent également être utilisées dans des scripts serveur pour générer des contenus dynamiques.

Exemple — Générer un rapport avec des icônes :

# Dans un script serveur
from frappe.utils import icon

def get_report_data():
    data = []
    for row in frappe.db.get_all("Task", fields=["name", "status"]):
        icon_name = "check-circle" if row.status == "Completed" else "alert-circle"
        data.append({
            "task": row.name,
            "status": f"{icon(icon_name, 'sm')} {row.status}"
        })
    return data

Utiliser des icônes personnalisées dans un tableau de bord

Les icônes personnalisées peuvent être utilisées dans les configurations de tableau de bord pour améliorer la lisibilité.

Exemple — Configurer un tableau de bord avec des icônes :

# Dans la configuration d'un tableau de bord
dashboard_config = {
    "cards": [
        {
            "label": "Projets en cours",
            "value": frappe.db.count("Project", {"status": "Open"}),
            "indicator": "blue",
            "icon": "ma-societe-projet"
        },
        {
            "label": "Tâches terminées",
            "value": frappe.db.count("Task", {"status": "Completed"}),
            "indicator": "green",
            "icon": "check-circle"
        }
    ]
}

Conclusion

Les icônes personnalisées offrent une flexibilité accrue pour adapter l'interface de Dokos à vos besoins spécifiques. Que ce soit pour renforcer l'identité visuelle de votre organisation, améliorer la clarté des types de documents ou personnaliser des composants d'interface, cette fonctionnalité vous permet de créer une expérience utilisateur plus intuitive et cohérente.

Pour aller plus loin, consultez les ressources suivantes :