Label Designer

Guide d’utilisation de Label Designer

Ce document décrit, étape par étape, l’installation, la configuration et l’utilisation du module Label Designer 1.0.0 pour Dolibarr.

1. Présentation du module

Label Designer permet de créer des modèles d’étiquettes visuellement, puis de générer des fichiers PDF à partir des données présentes dans Dolibarr.

Le module prend en charge quatre types d’objets :

  • les produits et services ;
  • les lots de produits ;
  • les entrepôts ;
  • les tiers (clients et fournisseurs).

Un modèle est créé pour chaque type d’objet. Ce modèle est réutilisé automatiquement : il n’est donc pas nécessaire de concevoir une étiquette différente pour chaque produit, lot, entrepôt ou tiers. Lors de la génération du PDF, les variables du modèle sont remplacées par les données de l’objet courant.

2. Prérequis

Avant l’installation, vérifier les éléments suivants :

  • Dolibarr 15 ou une version supérieure est installé ;
  • PHP 7.1 ou une version supérieure est disponible ;
  • le module Codes-barres de Dolibarr est disponible ;
  • le serveur web dispose d’un accès en écriture au répertoire des documents Dolibarr.

3. Installation et activation

  1. Copier le dossier labeldesigner dans htdocs/custom/.
  2. Se connecter à Dolibarr avec un compte administrateur.
  3. Ouvrir Accueil > Configuration > Modules/Applications.
  4. Rechercher Label Designer.
  5. Activer le module.
  6. Vérifier que le module Codes-barres est également activé.

Lors de son activation, Label Designer prépare son répertoire de stockage dans les documents Dolibarr et active l’utilisation des codes-barres pour les produits et les tiers.

4. Configuration des droits utilisateurs

  1. Ouvrir la fiche de l’utilisateur ou du groupe concerné.
  2. Accéder à l’onglet Permissions.
  3. Accorder les droits Label Designer nécessaires :
    • lecture des étiquettes ;
    • création et modification des modèles et des PDF.
  4. Vérifier que l’utilisateur possède aussi le droit de consulter l’objet concerné : produit, lot, entrepôt ou tiers.

Sans les permissions de l’objet, certaines données ou variables peuvent ne pas être accessibles.

Après une mise à jour ayant ajouté ou modifié les permissions du module, désactiver puis réactiver Label Designer afin que Dolibarr enregistre les nouvelles permissions. Il est ensuite possible d’accorder séparément Lire les étiquettes et Créer les étiquettes aux utilisateurs et aux groupes.

5. Accéder à une étiquette

  1. Ouvrir la fiche d’un produit, d’un lot, d’un entrepôt ou d’un tiers.
  2. Cliquer sur l’onglet Étiquette appartenant à Label Designer.
  3. La page affiche :
    • les paramètres de l’étiquette ;
    • le bouton Card Designer ;
    • le bouton Réinitialiser les paramètres ;
    • la zone des fichiers PDF générés ;
    • le bouton Générer.

Si un autre module ajoute également un onglet nommé Étiquette, identifier celui de Label Designer à partir de son adresse ou de son contenu.

6. Régler les paramètres de l’étiquette

Les paramètres sont enregistrés séparément pour chaque type d’objet.

Paramètre Utilisation
Largeur du document Largeur finale d’une étiquette, en millimètres
Hauteur du document Hauteur finale d’une étiquette, en millimètres
Largeur du code-barres Largeur du code-barres dans le modèle et le PDF
Hauteur du code-barres Hauteur du code-barres dans le modèle et le PDF
Largeur des barres Épaisseur visuelle des barres, entre 0,2 et 1,0 mm
Taille pixel Résolution de génération du QR code ; valeur par défaut : 250
Afficher la valeur du code-barres Affiche ou masque le texte sous le code-barres
Nombre d’étiquettes horizontalement Nombre de copies placées horizontalement dans le PDF final
Nombre d’étiquettes verticalement Nombre de copies placées verticalement dans le PDF final

Pour modifier une valeur :

  1. Cliquer sur l’icône en forme de crayon.
  2. Saisir la nouvelle valeur.
  3. Valider la modification.

Les dimensions du code-barres et du QR code sont synchronisées avec le modèle Card Designer. Une modification effectuée dans les paramètres met à jour le modèle ; une modification de taille effectuée dans Card Designer met également à jour les paramètres concernés.

Le bouton Réinitialiser les paramètres restaure les valeurs par défaut du type d’objet affiché.

7. Créer un modèle dans Card Designer

Les modèles fournis sont vides afin de laisser l’utilisateur construire sa propre étiquette.

  1. Depuis l’onglet Étiquette, régler d’abord la largeur et la hauteur du document.
  2. Cliquer sur Card Designer.
  3. Utiliser la barre d’outils pour ajouter les éléments souhaités :
    • Formes pour insérer des formes graphiques ;
    • Texte pour ajouter un texte libre ;
    • Variables pour ajouter une donnée dynamique de Dolibarr ;
    • Photos pour utiliser une image importée ;
    • Autocollants pour ajouter un élément décoratif ;
    • Couleur pour modifier la couleur d’un élément ;
    • Aligner pour positionner les éléments ;
    • Supprimer pour retirer l’élément sélectionné.
  4. Déplacer et redimensionner chaque élément directement sur la zone de travail.
  5. Cliquer sur Save.
  6. Confirmer l’enregistrement.

L’enregistrement crée uniquement le modèle JSON. Il ne génère pas de PDF. Après confirmation, Card Designer retourne vers la fiche de l’objet.

8. Ajouter des variables dynamiques

Dans Card Designer, cliquer sur Variables du produit, Variables du lot, Variables de l’entrepôt ou Variables du tiers, selon l’objet ouvert. Cliquer ensuite sur une variable pour l’ajouter au modèle.

8.1 Variables de produit

Les principales variables disponibles sont : référence, libellé, description, prix hors taxes, prix toutes taxes comprises, taux de TVA, catégorie, code-barres, QR code, et champs supplémentaires du produit.

Les prix et le taux de TVA sont formatés avec deux chiffres après la virgule.

8.2 Variables de lot

Les principales variables disponibles sont : référence du lot, référence du produit lié, libellé du produit, description du produit, DLC, DMD/DLUO, code-barres (à partir de la référence du lot), QR code (à partir de la référence du lot), et champs supplémentaires du lot.

8.3 Variables d’entrepôt

Les principales variables disponibles sont : référence, libellé, description, lieu et adresse, code postal et ville, projet lié (référence et titre), catégories ou tags, code-barres (à partir de la référence de l’entrepôt), QR code (à partir de la référence de l’entrepôt), et champs supplémentaires de l’entrepôt.

8.4 Variables de tiers

Les principales variables disponibles sont : nom du tiers, code client, code fournisseur, adresse, code postal et ville, adresse électronique et téléphone, code-barres, QR code, et champs supplémentaires du tiers.

8.5 Champs supplémentaires

Les champs supplémentaires configurés dans Dolibarr sont ajoutés automatiquement à la liste des variables de l’objet. Leur nom technique est associé à un libellé lisible dans Card Designer. Si un champ supplémentaire est vide pour l’objet courant, son emplacement peut apparaître sous forme de variable dans Card Designer, mais aucune valeur ne sera imprimée dans le PDF.

9. Utiliser les codes-barres et les QR codes

Produits et tiers

Le code-barres et le QR code sont proposés uniquement si :

  • le module Codes-barres est activé ;
  • l’utilisation des codes-barres est activée pour le type d’objet concerné dans la configuration Dolibarr ;
  • l’objet possède une valeur de code-barres.

Si le produit ou le tiers ne possède pas de code-barres, Card Designer peut afficher le nom de la variable comme repère, mais aucun code fictif n’est imprimé dans le PDF.

Lots et entrepôts

Le code-barres et le QR code utilisent la référence du lot ou de l’entrepôt. Une référence vide produit donc un emplacement vide dans le PDF.

Taille pixel du QR code

La taille pixel contrôle la résolution de l’image générée pour le QR code. Une valeur plus élevée améliore la netteté lors d’un agrandissement, mais augmente le poids des données. La valeur par défaut de 250 convient à la majorité des étiquettes.

10. Importer et utiliser des photos

  1. Dans Card Designer, cliquer sur Photos.
  2. Un QR code d’importation apparaît.
  3. Scanner ce QR code avec un téléphone, ou ouvrir directement la page d’importation.
  4. Sélectionner les images à envoyer au format PNG, JPG ou JPEG.
  5. Valider l’importation.
  6. Revenir dans Card Designer et rouvrir la bibliothèque Photos si nécessaire.
  7. Cliquer sur la photo souhaitée pour l’insérer dans l’étiquette.
  8. Déplacer et redimensionner l’image, puis enregistrer le modèle.

La page d’importation sert uniquement à envoyer les fichiers. La mise en page de la photo se fait ensuite dans Card Designer.

11. Générer le PDF

  1. Ouvrir la fiche de l’objet à imprimer.
  2. Accéder à son onglet Étiquette.
  3. Vérifier les paramètres et les données de l’objet.
  4. Cliquer sur Générer.
  5. Le module charge le modèle du type d’objet.
  6. Les variables sont remplacées par les données de l’objet courant.
  7. Le PDF est généré avec Fabric.js et jsPDF.
  8. Le fichier apparaît dans la zone Fichiers joints.
  9. Cliquer sur le nom du PDF ou sur l’icône d’aperçu pour le consulter.

Le même modèle peut donc produire successivement les étiquettes de plusieurs objets différents. Le nombre d’étiquettes horizontal et vertical est appliqué uniquement au PDF final. Il permet de répéter l’étiquette sans modifier le modèle Card Designer.

12. Modifier un modèle existant

  1. Ouvrir n’importe quel objet du type concerné.
  2. Accéder à l’onglet Étiquette.
  3. Cliquer sur Card Designer.
  4. Modifier le modèle.
  5. Cliquer sur Save et confirmer.
  6. Générer de nouveau le PDF.

La modification s’applique à toutes les prochaines étiquettes du même type. Les PDF déjà générés ne sont pas modifiés automatiquement.

13. Configuration de l’impression Bluetooth

La page Accueil > Configuration > Modules/Applications > Label Designer contient deux options activables :

  • Labeldesigner sur imprimante Bluetooth : active les fonctions prévues pour l’impression Bluetooth ;
  • Remplacer les caractères accentués sur imprimantes Bluetooth : remplace les caractères que certaines imprimantes ne savent pas imprimer correctement.

L’impression Bluetooth est désactivée par défaut. La seconde option n’est utile que lorsque la première est activée et que l’imprimante rencontre des problèmes avec les caractères accentués.

14. Conseils de conception

  • Définir les dimensions du document avant de commencer la mise en page.
  • Conserver une marge autour de l’étiquette pour éviter les coupures à l’impression.
  • Ne pas étirer excessivement un code-barres ou un QR code.
  • Effectuer un test d’impression et vérifier la lecture des codes avec un scanner.
  • Utiliser des images suffisamment nettes, sans résolution inutilement élevée.
  • Laisser assez d’espace pour les variables dont la longueur change selon l’objet.
  • Enregistrer le modèle avant de quitter Card Designer.

15. Dépannage

Le bouton Save retourne une erreur HTTP 500

Vérifier que le serveur web peut écrire dans le répertoire des documents Dolibarr, notamment dans le dossier réservé aux modèles Label Designer. Désactiver puis réactiver le module peut recréer le dossier nécessaire. Consulter également le journal PHP ou le journal du serveur web pour obtenir le message exact.

Le PDF est vide

Vérifier qu’un modèle contenant des éléments a été enregistré pour ce type d’objet. Les modèles installés par défaut sont volontairement vides.

Une variable est visible dans Card Designer mais absente du PDF

Vérifier que le champ est renseigné sur l’objet utilisé pour la génération. Une variable vide n’est pas remplacée par une valeur fictive.

Les champs supplémentaires ne sont pas visibles

Vérifier que les champs supplémentaires sont activés pour le bon type d’objet et que l’utilisateur dispose des permissions nécessaires. Recharger Card Designer après l’ajout d’un nouveau champ.

Le code-barres ou le QR code n’est pas disponible

Pour un produit ou un tiers, vérifier l’activation du module Codes-barres, l’option d’utilisation pour le type d’objet et la présence d’une valeur sur la fiche. Pour un lot ou un entrepôt, vérifier que la référence n’est pas vide.

Une modification de taille ne semble pas appliquée

Enregistrer la valeur, recharger Card Designer si celui-ci était déjà ouvert, puis générer un nouveau PDF. Vérifier que l’on consulte bien le dernier fichier produit.

L’affichage conserve une ancienne version

Actualiser la page avec un rechargement complet du navigateur. Si nécessaire, vider le cache de Dolibarr et le cache du navigateur.

16. Stockage et sauvegarde

Les modèles Card Designer sont enregistrés sous forme de fichiers JSON dans le répertoire des documents Dolibarr réservé au module. Les PDF générés sont stockés dans les documents associés aux objets.

Pour sauvegarder entièrement la configuration du module, inclure dans la stratégie de sauvegarde : la base de données Dolibarr, le répertoire des documents Dolibarr, et le dossier du module Label Designer.

Ne pas modifier manuellement les fichiers JSON pendant qu’un utilisateur travaille dans Card Designer.