L’Outil Surpuissant pour Exploser ton Chiffre d'Affaires en 2024 !
Utilisation de Storybook pour le développement Sitecore SXA
Ces dernières années, nous avons utilisé Storybook pour le développement de thèmes Sitecore SXA. Il nous a fourni quelques fonctionnalités clés qui nous aident à accélérer notre flux de travail de développement front-end (FED):
- Environnement de développement de nœuds avec Hot Module Reloading (HMR)
- Environnement déconnecté non dépendant de Sitecore
- Community Add -on pour faciliter les tests d'accessibilité Web (a11y)
- Documentation à la volée avec Module complémentaire Docs
En plus des avantages de l'expérience de développement ci-dessus, l'utilisation de Storybook donne également aux FED un flux de travail cohérent lors du déplacement entre les projets créés sur les CMS au-delà de Sitecore, par exemple Episerver.
Cet article traitera des sujets suivants:
- Qu'est-ce que Storybook?
- Configurer Storybook dans un thème SXA
- Personnalisation du thème Storybook pour votre marque
- Utilisation des actifs publics
- Utilisation du thème Sass et JavaScript dans Storybook
- Utilisation du code de modèle [19659003] Flux de travail de développement et conclusion
Nous allons commencer avec un nouveau thème SXA, mais si vous souhaitez voir la graine de Storybook terminée, veuillez visiter ce dépôt Github . Il ne contient que les fichiers Storybook pertinents pour faciliter son insertion dans n'importe quel projet.
Partie 1. Qu'est-ce que Storybook
Selon les propres mots de l'organisation:
Storybook est un outil open source pour développer des composants d'interface utilisateur de manière isolée pour React, Vue, Angular et plus encore. Cela rend la création d'interfaces utilisateur époustouflantes organisée et efficace.
L'installation de Storybook dans un projet ajoute un bac à sable de développement Node.js local qui permet aux développeurs de créer, tester et documenter des composants de manière isolée.
Lors du lancement de l'interface utilisateur Storybook, les FED de Sitecore peuvent testez le Sass et le JS importés ultérieurement dans Sitecore (SXA) ou regroupés sur un serveur. Les projets traditionnels impliquaient souvent une gamme vertigineuse de fichiers HTML référençant certains ou tous les actifs source. Storybook rend cela cohérent et augmente l'expérience des développeurs avec une variété de plugins officiels ainsi que l'accès à toute une communauté d'add-ons open-source. Jetons un coup d'œil à l'ajout de Storybook à un thème SXA.
Partie 2. Configuration d'un Storybook dans un thème SXA
Maintenant que nous avons une idée de ce qu'est Storybook et pourquoi l'utiliser, explorons l'ajout dans votre Thème SXA.
Les exemples ci-dessous partent du principe que vous travaillez dans un thème SXA traditionnel. La structure du répertoire dépend de vous, mais vous devrez peut-être mettre à jour les références / importations en fonction de vos préférences.
Structure du répertoire:
theme / ├── - / │ ├── scriban / │ └── metadata.json ├── avale / ├── sass / ├── scripts / ├── sources ├── styles ├── package.json └── LISEZMOI.md
- Ajoutez les dépendances suivantes à votre package.json:
// package.json { "scripts": { "dev": "start-storybook -p 6006 -s public" }, "dépendances": { "prop-types": "^ 15.7.2", "réagir": "^ 17.0.1", "react-dom": "^ 17.0.1" }, "devDependencies": { "@ babel / preset-react": "^ 7.10.4", "@ storybook / addon-a11y": "^ 6.1.14", "@ storybook / addon-actions": "^ 6.1.14", "@ storybook / addon-essentials": "^ 6.1.14", "@ storybook / addon-links": "^ 6.1.14", "@ storybook / addons": "^ 6.1.14", "@ storybook / node-logger": "^ 6.1.14", "@ storybook / react": "^ 6.1.14", "@ storybook / thématisation": "^ 6.1.14", "babel-loader": "^ 8.2.2", "core-js": "^ 3.8.3", "css-loader": "^ 5.0.1", "chargeur de fichiers": "^ 6.2.0", "html-loader": "^ 1.3.2", "sass-loader": "^ 10.1.1", "style-loader": "^ 2.0.0", "webpack": "^ 4.44.2", "webpack-cli": "^ 3.3.12" } }npm install
Installez les dépendances avec la commande ci-dessus
- Mettez à jour votre configuration babel pour inclure les éléments suivants:
{ "babel": { "préréglages": [ "@babel/env", "@babel/preset-react" ] } } - Créez un dossier .storybook dans votre répertoire avec les fichiers et contenus suivants:
thème / ├── .storybook / │ ├── main.js │ └── preview.js └── ...
// main.js const path = require ('path'); module.exports = { 'histoires': [ '../src/**/*.stories.@(js|jsx)' // configures where story files are located ], 'addons': [ // adds necessary addons to the project '@storybook/addon-links', '@storybook/addon-essentials', '@storybook/addon-a11y' ], // configuration Webpack personnalisée webpackFinal: async (config, {configType}) => { config.module.rules.push ({ test: /.(js|jsx)$/, exclure: / node_modules /, utiliser: [ 'babel-loader', ], }); config.module.rules.push ({ test: /.scss$/, utiliser: [ 'style-loader', 'css-loader', 'sass-loader', ], exclure: / node_modules /, }); config.module.rules.push ({ test: /.(woff|woff2|eot|ttf|otf)$/, utiliser: [ 'file-loader' ], inclure: path.resolve (__ dirname, '../') }); config.module.rules.push ({ test: /.(html|cshtml|scriban)$/, utiliser: [ 'html-loader' ], inclure: path.resolve (__ dirname, '../') }); return config; }, }// preview.js // laisser vide pour le moment, nous discuterons de l'importation des éléments de thème dans une section suivante
- Créez votre première histoire – dans la racine du thème, créez un répertoire src / et à l'intérieur créez un fichier appelé example.stories.js avec le contenu suivant:
thème / ├── ... ├── src / │ └── histoires / │ └── example.stories.js └── ...
// importer les dépendances importer React depuis 'react'; // Métadonnées de l'histoire export par défaut { title: 'Test', // configure la structure du dossier Storybooks UI }; // une histoire (en tant que composant fonctionnel React) // vous pouvez avoir plusieurs histoires dans un fichier export const standard = () => (Yo!)Note : à l'étape 3 ci-dessus, nous avons ajouté une ligne qui configurera Storybook pour importer automatiquement tout fichier dans le thème / src / qui se termine par .stories.js, vous n'aurez donc pas besoin de le faire manuellement importez tous les fichiers d'histoire 🙂
- Exécutez Storybook – avec tout cela correctement configuré, vous devriez maintenant pouvoir ouvrir n'importe quel terminal et exécuter la commande suivante (précédemment ajoutée au package.json à l'étape 1):
npm run dev
- Ajoutez les dépendances suivantes à votre package.json:
Votre navigateur doit s'ouvrir sur http: // localhost: 6006 avec les éléments suivants
Avec Storybook opérationnel, tournons notre attention vers la personnalisation du thème Storybook.
Partie 3. Personnalisation du thème Storybook pour votre marque
Vous pouvez personnaliser diverses parties de l'interface utilisateur Storybook via l'API du thème . Avec cela, vous pouvez changer les polices, les styles, les couleurs d'arrière-plan, les logos et les favicons. Dans cette section, nous examinerons la modification des logos pour représenter la marque du site.
Storybook récupérera les personnalisations de l'API de thème à partir du dossier .storybook / dans un fichier appelé manager.js. Pour mettre à jour le logo principal et le favicon, créez ce fichier avec le contenu suivant:
theme / ├── .storybook / │ ├── main.js │ ├── manager.js // ajouter ce fichier │ └── preview.js └── ...
// manager.js
importer des {addons} depuis '@ storybook / addons';
import {create} depuis '@ storybook / theming / create';
thème const = créer ({
base: 'léger',
brandTitle: 'Storybook | Perficient ',
brandUrl: «https://www.perficient.com/»,
brandImage: './perficient-logo.svg',
});
addons.setConfig ({theme}); Remarque: Le chemin de l'image ci-dessus est relatif au dossier theme / public /, car il a été configuré comme répertoire statique dans la section «scripts» du package .json. Nous discuterons de l'utilisation du contenu statique dans une prochaine section.
Une fois ces personnalisations ajoutées, arrêtez et redémarrez le serveur Storybook et voyez les modifications
Check the Documentation de Storybook pour en savoir plus sur les options de personnalisation des thèmes.
Partie 4. Utilisation des actifs publics
Storybook simplifie le travail avec les actifs statiques. Dans la section «scripts» package.json, la commande se termine par l'indicateur -s avec l'emplacement du répertoire (public). Pour référencer des images, des polices, etc., ajoutez-les dans le répertoire public et référencez-les via un chemin relatif à ce répertoire, par exemple theme / public / images / logo.svg, peut être référencé avec le chemin suivant:
Nous avons constaté que l'imitation du chemin de la médiathèque de Sitecore était utile pour résoudre les URL.
Partie 5. Travailler avec SCSS et JS dans Storybook
Il n'est pas difficile de travailler avec le thème SXA Scss et JS, mais il y a quelques pièges. Cette section vous montrera comment importer vos fichiers source et résoudre les erreurs de variables globales.
SCSS dans Storybook
Dans la section 2 (ci-dessus), nous avons créé un fichier preview.js vide dans le dossier .storybook /. Ce fichier sert à importer globalement des ressources JS et SCSS dans votre projet. Nous allons l'utiliser pour importer tout le thème Sass dans notre projet. Pour ce faire, créez simplement un fichier .scss et importez tous les styles nécessaires. Nous récupérons également les fichiers optimisés.min.css nécessaires (à partir de Sitecore) et les ajoutons au dossier src pour avoir la grille, etc.
JS dans Storybook
L'importation du composant JS se fera principalement dans le fichier story, et nous examinerons un exemple ci-dessous. Les ressources JS globales (ex une bibliothèque tierce) peuvent simplement être importées dans le fichier preview.js.
Travailler avec le composant SXA JS dans Storybook nécessite deux étapes principales:
- Création et importation d'un objet XA global. Cela est nécessaire pour simuler l'initialisation du composant XA dans l'API exposée de votre composant. Pour simuler cela, créez un fichier xa-mock.js dans le dossier src avec le code ci-dessous. Vous pouvez l'importer globalement dans votre fichier preview.js.
// xa-mock.js global.XA = { composant: {}, S'inscrire() { } }; - Importation et initialisation d'un composant dans le fichier histoire. Puisque Storybook est construit sur React, chaque histoire est un composant fonctionnel. Afin d'initialiser correctement le composant et de se lier aux éléments DOM, vous devez exécuter la fonction init à l'intérieur du hook useEffect () React. Cela garantira que le DOM a terminé le rendu (à partir de React) avant d'essayer de lier les gestionnaires d'événements, etc. Jetons un coup d'œil à un exemple simple ci-dessous.
// thème / sources / mon-composant.js XA.component.myComponent = (() => { 'use strict'; const api = { initialisé: faux, init () { if (this.initialized) { revenir; } autre { const btn = document.querySelector ('# btn'); btn.addEventListener ('clic', () => { alert ('working !!'); }); } } } return api; }) (); XA.register ('mon-composant', XA.component.myComponent);// thème / src / stories / Test.stories.js // importer le hook useEffect import React, {useEffect} de 'react'; // composant d'importation import '../../sources/my-component'; // Métadonnées de l'histoire export par défaut { title: 'Test', }; export const standard = () => { // utilise le hook useEffect pour initialiser le composant useEffect (() => { XA.component.myComponent.init (); }, []); revenir () }Vous pouvez voir que nous avons simplement besoin d'importer le hook useEffect () React et de l'appeler dans le composant story comme moyen d'init () notre composant XA. Cela garantira que la méthode React render () a été appelée et que notre contenu DOM a terminé le rendu. Pour plus d'informations sur les hooks React, consultez la documentation .
Dans cette section, nous voyons qu'il y a une petite configuration pour utiliser le code de composant XA à l'intérieur de Storybook. Après les premières fois, cela deviendra une seconde nature, ou du moins un modèle à copier / coller 😉
Avant de jeter un œil à un flux de travail de développement pratique, examinons comment utiliser les fichiers .html ou .scriban pour agir comme le balisage de votre histoire de Storybook.
Partie 6. Utilisation du code de modèle
L'écriture de tout le balisage dans la syntaxe JSX peut parfois être décourageante, en particulier lors du copier-coller dans un fichier rasoir ou dans un bloc scriban dans le Arborescence de contenu Sitecore. (J'oublie souvent de changer className en class). Heureusement, nous pouvons écrire notre code de modèle dans des fichiers .scriban ou .html et les importer dans notre histoire.
En prenant l'exemple ci-dessus avec le gestionnaire de boutons, nous pouvons le refactoriser comme suit:
// thème / src / stories / Test.stories.js
import React, {useEffect} de 'react';
import '../../sources/my-component';
// modèle d'importation
const testScriban = require ('../../-/ scriban / Test / default.scriban')
// Métadonnées de l'histoire
export par défaut {
title: 'Test',
};
export const standard = () => {
useEffect (() => {
XA.component.myComponent.init ();
}, []);
// rendu avec dangerouslySetInnerHTML
revenir (
)
} Cela devrait rendre et fonctionner exactement comme avant. La différence est que notre code de modèle est extrait et peut être dans un format plus proche de la façon dont il sera utilisé par Sitecore. Une note sur l'utilisation des fichiers scriban avant de passer à autre chose: la syntaxe scriban ne peut pas être analysée via Node, car il n'y a pas d'analyseur pris en charge par les nœuds. Nous avons choisi d'utiliser ce format pour servir de modèle de contrat entre le développement frontal et l'implémentation de Sitecore.
Dans notre dernière section, nous discuterons d'un workflow de développement pratique.
Partie 7. Workflow de développement et conclusion
Maintenant que nous avons une meilleure compréhension de ce qu'est Storybook, comment l'inclure dans notre thème et comment l'utiliser pour travailler avec les fichiers de thème et le balisage, discutons d'un flux de travail typique.
Puisque le développement frontal est maintenant déconnecté de Sitecore pour permettre un développement plus rapide, les développeurs Sitecore peuvent se concentrer sur la création de modèles et de rendus tandis que les développeurs frontaux se concentrent sur la création d'actifs / styles / JS de thème. L'intégration est requise pour ajouter le balisage dans Sitecore: sous forme de composants .cshtml, .scriban ou SSR React. Cette étape sera un processus manuel, mais le balisage de Storybook fournira le guide. Nous trouvons utile de le considérer comme un développement axé sur le contrat, l’obligation étant sur le balisage. réduction nette du temps. De plus, nous voyons un réel avantage avec Storybook car il fournit une documentation de développement. De plus, Storybook fournit des commandes pour exporter une version statique du site qui peut être déployée sur un serveur d'hébergement. Enfin, plusieurs DSM (comme Invision) ont des points d'intégration dans Storybook pour améliorer la collaboration entre la conception et le développement.
Source link