🇫🇷 Sylius - Utiliser un thème externe

Sylius-external-theme.md

Sylius - Utiliser un thème externe

Introduction au thème dans Sylius

Les thèmes dans Sylius sont très utiles quand le fonctionnement d'override standard de Symfony atteint ses limites.

La documentation nous dit :

Quand utiliser les thèmes Sylius:

• vous avez plus d'un canal pour une seule instance Sylius
• et vous voulez que chaque canal ait son apparence et son comportement
• vous changez beaucoup de choses dans les vues

Créer un thème

On peut créer un thème de manière très simple en lançant les commandes suivantes depuis votre installation Sylius :

$ mkdir -p themes/AwesomeTheme
$ composer init -d themes/AwesomeTheme 
# Répondre au questionnaire de composer pour initialiser le composer.json. 
# Il n'y a pas de dépendances nécessaires
$ composer config extra.sylius-theme.title "Awesome Theme" -d themes/AwesomeTheme  

Et voila, nous avons un nouveau thème configurable sur chaque channel 🎉

Un thème alternatif, le BootstrapTheme

Sylius a créé en Février 2019 un nouveau thème basé sur l'excellent Framework Bootstrap.

Malheureusement, la procédure d'installation fournie propose de télécharger le thème, et l'inclure (et donc versionner) dans notre dossier thème, nous privant ainsi de potentielles mises à jour. Et comme ce thème est créé par l'équipe de Sylius en personne, on peut s'attendre a ce qu'il suive les mises à jours du framework.

Mais heureusement, en créant des thèmes avec un composer.json, on peut très bien le récupérer via notre gestionnaire de dépendances préféré : COMPOSER 🙌

$ composer require sylius/bootstrap-theme

Pour rendre ce nouveau thème disponible dans notre application, on va devoir altérer la configuration du bundle SyliusTheme :

# config/packages/_sylius.yaml
# [...]
sylius_theme:
    sources:  
        filesystem:  
            directories:  
                - "%kernel.project_dir%/vendor/sylius/bootstrap-theme"  
                - "%kernel.project_dir%/themes"

Dans la liste des directories, on indique au bundle d'aller regarder également dans les vendors.

Le thème est maintenant disponible sur notre configuration de channel.

Il conviendra bien sûr d'éxécuter le processus d'installation du thème pour avoir les assets. Pour cela, il faut suivre la documentation très complete du thème à l'éxception de l'étape 1 (la récupération du thème), et de l'étape 4, la configuration du webpack.config.js.

En effet, dans la configuration webpack d'exemple, le chemin pour aller récupérer la configuration webpack du thème n'est pas le bon, mais il y aura également une erreur dans la configuration webpack du thème, celui-ci s'attendant à être dans le dossier themes/BootstrapTheme.

Voici une configuration webpack qu'on peut utiliser à la place :

// webpack.config.js
const Encore = require('@symfony/webpack-encore');

Encore
  .setOutputPath('public/bootstrap-theme')
  .setPublicPath('/bootstrap-theme')
  .addEntry('app', './vendor/sylius/bootstrap-theme/assets/app.js')
  .disableSingleRuntimeChunk()
  .cleanupOutputBeforeBuild()
  .enableSassLoader()
  .enableSourceMaps(!Encore.isProduction())
  .enableVersioning(Encore.isProduction());

const config = Encore.getWebpackConfig();
config.name = 'bootstrapTheme';

module.exports = [config];

Et voila, vous pouvez maintenant utiliser le thème bootstrap sur votre application.

Personnaliser le thème

Évidemment, importer un thème de cette manière n'a pas d’intérêt si on ne peut pas le modifier pour l'adapter à notre boutique. C'est la qu'entre en scène l'héritage des thèmes !

Reprenons notre AwesomeTheme créé plus haut, et faisons le étendre du BootstrapTheme :

// themes/AwesomeTheme/composer.json
{
    "name": "barth/awesome-theme",
    "extra": {
        "sylius-theme": {
            "title": "Awesome Theme",
            "parents": ["sylius/bootstrap-theme"]
        }
    }
}

Et c'est tout. Notre AwesomeTheme aura le même affichage que le BootstrapTheme. À nous les joies du templating et de la customisation CSS 🎨

Aller plus loin

Le fonctionnement qu'on a mis en place peut-être ré-appliqué pour tout vos thèmes ! On peut imaginer que le BootstrapTheme soit le père de votre AgenceTheme, et lui même le père de votre ClientTheme.