Créer un thème

Cette page s'adresse aux graphistes et webdesigners qui veulent habiller une boutique OnePageBasket aux couleurs d'une marque. Aucune connaissance de Dolibarr n'est nécessaire : un thème se compose de fichiers HTML et CSS, et le module se charge de fournir les données.

Le principe en trois phrases

Un thème est un dossier posé dans themes/. Il ne contient que ce que vous voulez changer : tout ce qui manque est automatiquement repris du thème default. Vous pouvez donc livrer un thème d'un seul fichier CSS, ou un thème qui redéfinit toutes les pages.

themes/
├── default/        <- la référence, toujours complète
├── InfraS/
├── lumen/
├── marketplace/
├── shopiplace/
├── chacha/
├── nordic/
└── macharte/       <- votre thème

Quand la boutique affiche la page produit et que themes/macharte/product.blade.php n'existe pas, c'est themes/default/product.blade.php qui est utilisé, avec le CSS de macharte. C'est ce repli qui rend les thèmes légers.

Le seul vrai piège du système. Un gabarit que vous copiez est figé au jour de la copie : il ne recevra plus aucune évolution ultérieure de default. Plus vous copiez de gabarits, plus votre thème demandera de maintenance. Avant de copier un fichier, demandez-vous toujours si le besoin ne tient pas seulement au style : dans ce cas, le CSS suffit.

Trois niveaux d'effort

Les thèmes lumen, marketplace, shopiplace et chacha sont des thèmes de niveau "vitrine" : entre 7 et 12 fichiers chacun. Ce sont les meilleurs modèles à étudier avant de commencer.

Ce qu'il vous faut sur votre poste

• Un accès aux fichiers du module (custom/onepagebasket/ dans Dolibarr).
• Node.js avec npx disponible, pour compiler le CSS.
• Un éditeur de texte. Aucun autre outil n'est nécessaire.

Vérification rapide :

npx tailwindcss --help

Étape 1 - Créer le dossier

mkdir -p themes/macharte/tools

Le nom du dossier est celui qui apparaîtra dans l'administration. Utilisez uniquement des lettres, chiffres, tirets et soulignés : les autres noms sont ignorés par le module.

Étape 2 - Le fichier input.css

C'est le coeur du thème. Il définit la palette, les polices et les arrondis. Voici un fichier de départ complet, prêt à être modifié :

@import "tailwindcss" source(none);
@tailwind base;
@tailwind components;
@tailwind utilities;
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

/*
 * Sources à scanner. Ce bloc est OBLIGATOIRE et ne doit pas être raccourci :
 * il liste les fichiers où Tailwind va chercher les classes utilisées.
 * Le thème hérite des gabarits de default/, donc leurs classes doivent être
 * compilées ici aussi, sinon la boutique s'affiche en HTML brut sur toutes
 * les pages que votre thème ne redéfinit pas.
 */
@source "./*.blade.php";
@source "./**/*.blade.php";
@source "../default/*.blade.php";
@source "../default/**/*.blade.php";
@source "../../public/**/*.{html,js,php}";
@source "../../langs/*/*.lang";

@plugin "daisyui" {
    themes: light --default, dark --prefersdark;
}

/* ============================================================
 * Palette - mode clair
 * ============================================================ */
[data-theme="light"],
:root:has(input.theme-controller[value=light]:checked),
:where(:root) {
    --color-primary: #B4794E;          /* couleur d'action principale */
    --color-primary-content: #ffffff;  /* texte posé sur la couleur primaire */
    --color-secondary: #17171A;
    --color-secondary-content: #ffffff;
    --color-accent: #9A6A3C;           /* survol, accents */
    --color-accent-content: #ffffff;
    --color-neutral: #17171A;
    --color-neutral-content: #F6F5F1;
    --color-base-100: #ffffff;         /* cartes, surfaces */
    --color-base-200: #F6F5F1;         /* fond de page */
    --color-base-300: #E7E5DE;         /* bordures, séparateurs */
    --color-base-content: #17171A;     /* couleur du texte */
    --color-info: #2F6FB0;
    --color-info-content: #ffffff;
    --color-success: #2E7D5B;
    --color-success-content: #ffffff;
    --color-warning: #B8860B;
    --color-warning-content: #ffffff;
    --color-error: #C0392B;            /* suppression, promotions */
    --color-error-content: #ffffff;
    --radius-box: 1rem;                /* arrondi des cartes */
    --radius-field: 0.625rem;          /* arrondi des champs et boutons */
    --radius-selector: 0.5rem;
}

/* ============================================================
 * Palette - mode sombre
 * ============================================================ */
[data-theme="dark"] {
    --color-primary: #C68B5E;
    --color-primary-content: #1A1208;
    --color-secondary: #EDEBE6;
    --color-secondary-content: #18181B;
    --color-accent: #C68B5E;
    --color-accent-content: #1A1208;
    --color-neutral: #EDEBE6;
    --color-neutral-content: #18181B;
    --color-base-100: #1B1B1F;
    --color-base-200: #141417;
    --color-base-300: #2A2A2F;
    --color-base-content: #EDEBE6;
    --color-info: #5B93D6;
    --color-success: #4CAF82;
    --color-warning: #D7A53B;
    --color-error: #E06B5E;
}

/* ============================================================
 * Typographie
 * ============================================================ */
body {
    font-family: 'Inter', system-ui, -apple-system, sans-serif;
    -webkit-font-smoothing: antialiased;
    text-rendering: optimizeLegibility;
}

Ces variables sont celles de DaisyUI : en les redéfinissant, vous recolorez d'un coup tous les boutons, badges, alertes et cartes de la boutique, y compris sur les pages que votre thème ne redéfinit pas. C'est le meilleur rapport effort / résultat du système.

Pourquoi source(none) est obligatoire

Sans cette option, Tailwind v4 scanne toute la racine du projet. Chaque thème embarquerait alors les classes de tous les autres, et son CSS deviendrait périmé dès qu'un thème voisin change. Le fichier compilé passerait aussi de 230 Ko à plusieurs mégaoctets.

Seul le thème default omet les deux lignes ../default : il n'hérite de personne.

Les polices

Aucune ressource distante n'est autorisée : pas de Google Fonts, pas de CDN. Les polices sont servies depuis le dossier public/fonts/ de la boutique.

1. Déposez vos fichiers .woff2 dans public/fonts/.
2. Déclarez-les dans input.css avec un chemin ./fonts/... :

@font-face {
    font-family: 'Fraunces';
    src: url('./fonts/Fraunces.woff2') format('woff2');
    font-weight: 100 900;
    font-style: normal;
    font-display: swap;
}

Le chemin commence par ./fonts/ et non ../../public/fonts/ : la feuille de style est distribuée par un script situé à la racine publique de la boutique, c'est donc de là que le navigateur résout les URL.

Choisissez des polices libres de droits pour la diffusion web (licence OFL par exemple). Les polices déjà disponibles sont Inter, Fraunces, Lato, Montserrat, Poppins.

Étape 3 - Compiler le CSS

Ajoutez la cible de compilation dans Makefile.dist, à côté des autres :

css-macharte: themes/macharte/*
    npx tailwindcss -i ./themes/macharte/input.css -o ./themes/macharte/index.css

Puis ajoutez css-macharte à la ligne .PHONY et à la cible groupée css.

Compilation :

make css-macharte     # votre thème seul
make css              # tous les thèmes

Le fichier produit, themes/macharte/index.css, doit être livré avec le thème : c'est lui que la boutique sert aux visiteurs. Après toute modification d'un gabarit ou du input.css, recompilez. Un gabarit modifié sans recompilation affiche des classes CSS qui n'existent pas dans la feuille de style.

Étape 4 - Activer le thème

Dans Dolibarr : Accueil > Configuration > Modules > OnePageBasket > icône engrenage > onglet Apparence. Votre thème apparaît dans la liste déroulante dès que le dossier existe.

Deux réglages voisins vous concernent :

Prévisualiser sans changer la configuration

Si le mode démonstration est activé, une barre apparaît en bas de la boutique avec un sélecteur de thème. Le thème choisi ne vaut que pour votre propre navigateur : c'est le moyen le plus simple de comparer plusieurs pistes graphiques sur une boutique en fonctionnement.

Étape 5 - Redéfinir des gabarits

Les pages sont écrites en Blade, un langage de gabarits très proche du HTML.

La syntaxe qu'il faut connaître

Une page type ressemble à ceci :

@extends('app')

@section('content')
    <section class="py-12 bg-base-200">
        <div class="container mx-auto px-4">
            <h1 class="text-3xl font-bold">{{ $title }}</h1>
        </div>
    </section>
@endsection

Règle de copie

Quand vous décidez de redéfinir un gabarit :

1. Partez toujours de la version du jour de themes/default/, jamais d'une copie prise dans un autre thème.
2. Conservez toutes les variables et tous les @include d'origine. Le style se change, la logique se garde.
3. Ne réécrivez jamais en ligne un morceau qui existe en partagé. Si le partagé ne vous convient pas visuellement, créez votre propre themes/macharte/tools/<nom>.blade.php avec la même interface : le repli fera le reste et la page appelante n'a pas à savoir quel thème est actif.

Anatomie des gabarits

Structure générale

Pages boutique

Parcours client

Portail client

dashboard.blade.php et le dossier dashboard/ (une trentaine de fichiers : orders, invoices, contracts, wishlist, returns_list, myaccount...). La plupart des thèmes ne les redéfinissent pas : ce sont des pages de gestion où le CSS suffit largement.

Morceaux partagés (tools/)

Ce sont les briques réutilisées d'une page à l'autre. Les plus utiles à un webdesigner :

Le contrat à ne pas casser

Ces points sont vérifiés automatiquement par la suite de tests du module. Un thème qui les enfreint fait échouer les tests et casse des fonctionnalités que le commerçant a payées.

Éléments obligatoires par gabarit

Si vous redéfinissez header.blade.php, il doit contenir :

Si vous redéfinissez footer.blade.php : $pages_menu_footer, $socname et le bloc libre du commerçant, soit par @include('tools.footer_freeblock'), soit en lisant directement $footer_col1_title et $footer_col1_html.

Si vous redéfinissez product.blade.php : $product_is_promo, $product_promo_percent et $product_price_promo, sans quoi les promotions disparaissent de la fiche produit.

Si vous redéfinissez register.blade.php : $messageWarn (le retour d'erreur du contrôle serveur, sans lequel un formulaire refusé se réaffiche sans aucune explication) et $register_vat_required.

Si vous redéfinissez index.blade.php : la grille du catalogue doit passer par @include('tools.productcard', ...), jamais par une carte écrite en ligne.

Crochets JavaScript à préserver

Le module fournit des comportements qui s'accrochent à des attributs précis. Si vous refaites un bloc HTML, gardez-les.

Les données disponibles dans les gabarits

Toutes les pages reçoivent ce contexte commun. Utilisez-le plutôt que d'écrire des valeurs en dur.

Identité et coordonnées

Page et référencement

Attention. $canonical est l'adresse de base de la boutique, pas l'adresse de la page courante. Pour la balise canonique, les gabarits écrivent {{ $og_url ?? $canonical }}. Ne redéfinissez pas $canonical : vous casseriez toutes les URL d'images.

Contenus de la page d'accueil

Menus et navigation

Fonctionnalités activées

Ces indicateurs valent 1 ou vide. Ils servent à masquer proprement ce que le commerçant n'a pas activé.

$setup_shop_enabled, $setup_portal_enabled, $setup_payment_enabled, $setup_use_ttc (prix affichés TTC ou HT), $setup_stock_enabled, $setup_support_enabled, $setup_show_quotation, $setup_show_quotation_button, $setup_portal_pay_enabled, $setup_portal_sign_enabled, $setup_portal_shop_basket_enabled, $withdrawal_enabled, $returns_enabled, $wishlist_enabled, $prices_visible (les prix sont-ils réservés aux clients connectés), $prices_hidden_text.

Client connecté

$auth_login, $cus_soc, $cus_name, $cus_firstname, $cus_email, $cus_phone, $cus_address, $cus_zip, $cus_town, $cus_country, $cus_vat, $cus_url, $wishlist_count, $country_select (liste déroulante des pays, déjà construite).

Formulaires

Tout formulaire doit contenir :

<input type="hidden" name="token" value="{{ $newToken }}">

Les images

Les images ne sont jamais servies par leur chemin de fichier, mais par un script qui contrôle les droits d'accès :

<img src="/img/onepagebasket/%7B%21%21%20%24canonical%20%21%21%7D/image.php%3Fi%3D%7B%7B%20%24article-%3Eimghash%20%7D%7D" alt="{{ $article->label }}">

$css_url et $favicon_url sont fournies prêtes à l'emploi : elles portent l'empreinte de cache et, en mode démonstration, le thème choisi par le visiteur. Ne les reconstruisez pas à la main, sinon la prévisualisation de thème servira la feuille de style d'un autre thème.

Pensez au chargement différé sur les grilles de produits : les quatre premières cartes en loading="eager" et fetchpriority="high", les suivantes en loading="lazy". Le partial tools/productcard de default montre le motif.

Les textes

Aucun texte en dur dans un gabarit. La boutique existe en huit langues (français, anglais, espagnol, italien, allemand, néerlandais, polonais, portugais du Brésil). Tout libellé passe par :

{{ __('opbAddToCart') }}

Si votre thème introduit un libellé qui n'existe pas encore, la clé doit être ajoutée dans les fichiers langs/*/onepagebasket.lang, dans les huit langues. Une clé manquante s'affiche telle quelle à l'écran.

Pour les textes réutilisés d'une page à l'autre, cherchez d'abord la clé existante dans langs/fr_FR/onepagebasket.lang avant d'en créer une.

Une couleur pilotable par le commerçant

Le réglage Couleur principale du thème (onglet Apparence) permet au commerçant de recolorer la boutique sans vous rappeler ni recompiler le CSS. Pour en profiter, créez un partial tools/theme_color.blade.php dans votre thème, inclus depuis votre app.blade.php, qui redéfinit les variables de couleur à l'exécution.

Trois fonctions utilitaires sont disponibles :

Le thème shopiplace implémente ce motif : c'est le modèle à recopier. Une palette entière y est dérivée d'une seule couleur saisie par le commerçant.

Règles de production

• Jamais de ressource distante. Ni CDN, ni Google Fonts, ni bibliothèque d'icônes en ligne. Tout doit fonctionner sur une boutique sans accès Internet sortant, et rien ne doit fuiter vers un tiers pour des raisons de RGPD. FontAwesome est déjà embarqué localement et disponible dans tous les thèmes.
• Jamais de style en ligne (style="...") sur les éléments. Le CSS est compilé : un style en ligne échappe au thème et devient impossible à surcharger. L'exception admise est le partial theme_color décrit ci-dessus, dont c'est précisément le rôle.
• Utilisez les classes déjà présentes dans le codebase. Une classe Tailwind employée nulle part ailleurs et écrite dans un fichier non scanné ne sera pas compilée : elle n'aura aucun effet.
• Le mobile d'abord. La boutique est majoritairement consultée sur téléphone. Concevez en mobile puis élargissez avec sm:, md:, lg:.
• Le mode sombre est attendu. Chaque teinte a sa contrepartie sombre via le bloc [data-theme="dark"] et les variantes dark:.
• L'accessibilité n'est pas optionnelle. Attribut alt sur les images, aria-label sur les boutons sans texte, contraste suffisant entre les couleurs de fond et de texte, ordre de tabulation cohérent.

Checklist avant livraison

• [ ] input.css contient le bloc @source complet, source(none) inclus
• [ ] index.css est recompilé et livré avec les gabarits
• [ ] Les polices sont dans public/fonts/ et référencées en ./fonts/...
• [ ] Aucune adresse distante dans le CSS ni dans les gabarits
• [ ] Aucun texte en dur : tout passe par __('...')
• [ ] Les clés de traduction nouvelles existent dans les huit langues
• [ ] Chaque formulaire contient {{ $newToken }}
• [ ] Les marqueurs obligatoires sont présents dans les gabarits redéfinis
• [ ] Les crochets JavaScript sont conservés
• [ ] Rendu vérifié en mode clair et en mode sombre
• [ ] Rendu vérifié sur téléphone, tablette et grand écran
• [ ] Les pages non redéfinies (portail client, confirmations) restent lisibles
• [ ] La cible css-macharte est déclarée dans le Makefile
• [ ] favicon.png fourni si vous voulez un favicon propre au thème

Si vous avez accès à l'environnement de développement, lancez la suite de tests : elle signale précisément les marqueurs manquants.

vendor/bin/phpunit -c phpunit.xml

Erreurs fréquentes

Par où commencer concrètement

1. Copiez themes/lumen/input.css dans themes/macharte/input.css.
2. Remplacez les valeurs de couleur par celles de votre charte, dans les deux blocs clair et sombre.
3. Ajoutez la cible css-macharte au Makefile.dist et lancez make css-macharte.
4. Activez le thème dans l'onglet Apparence, et regardez : vous avez déjà une boutique complète à vos couleurs.
5. Copiez ensuite themes/default/tools/productcard.blade.php dans votre thème et retravaillez la carte produit. C'est l'élément le plus vu de la boutique.
6. Puis header.blade.php et footer.blade.php, en gardant les marqueurs obligatoires.
7. Enfin index.blade.php si la page d'accueil demande une composition particulière.

Arrêtez-vous dès que le résultat vous convient : chaque fichier que vous n'avez pas copié est un fichier qui continuera de s'améliorer tout seul au fil des mises à jour du module.

Voir aussi

• Configuration générale - où activer le thème et régler logo, favicon, carrousel et langues
• La boutique en ligne - les fonctionnalités que votre thème doit savoir afficher
• Pages de contenu - les pages libres alimentées par le commerçant