Édition par @david : Le système de thématique de Discourse prend désormais en charge nativement plusieurs fichiers JS. Cette méthode Webpack n’est plus nécessaire.
Bonjour ! Alors que je développais mon composant handsfree-discourse, j’ai rencontré quelques problèmes de gestion de fichiers. Mon principal souci était de trouver un moyen de diviser mon code en plusieurs fichiers. L’autre problème était la nécessité d’inclure des bibliothèques tierces sans demander aux administrateurs d’activer CORS ou de déclencher des requêtes HTTP supplémentaires.
Pour résoudre ces problèmes, j’ai créé discourse-webpack, un modèle pour créer rapidement des composants riches en JS ! Les fonctionnalités incluent :
- Un serveur de développement local avec rechargement à chaud (live reloading)
- Un script de commit inclus pour maintenir votre code source et votre code compilé dans des branches séparées !
Le reste de ce sujet explique comment l’utiliser et pourquoi cela fonctionne. Je viens tout juste de terminer les tests pour quelques autres composants sur lesquels je travaille, alors n’hésitez pas à me faire part de vos problèmes ou de vos demandes spécifiques !
Créez rapidement des composants riches en JavaScript pour votre communauté Discourse, avec un script de commit pour maintenir votre code source et votre code de construction dans des branches séparées afin de vous aider à livrer vite !
Installation
Assurez-vous d’abord d’avoir NodeJS >= 8 et git installés localement sur votre machine. Ensuite, tapez chacune des lignes ci-dessous :
# Télécharger ce dépôt
git clone https://github.com/browsehandsfree/discourse-webpack
# Se déplacer dans le répertoire
cd discourse-webpack
# Installer les dépendances
npm install
Vous devrez ensuite modifier les éléments suivants dans package.json, en remplaçant tous nos liens par les vôtres. Plus précisément :
{
name: 'votre-projet',
repository: {
url: 'git+https://github.com/nomutilisateur/repo'
},
author: '',
bugs: {
url: 'https://github.com/nomutilisateur/repo/issues'
},
homepage: 'https://exemple.com'
}
Plus important encore, assurez-vous que repository.url est correct et qu’il est précédé de git+. Lorsque vous exécutez npm run discourse, il effectuera un commit et un push vers ce dépôt.
N’oubliez pas non plus de configurer votre about.json de Discourse, qui se trouve dans /src/discourse/about.json.
Développement
Après npm install, vous obtiendrez la structure de répertoire suivante :
discourse-webpack
|- node_modules/ # Dépendances
|- src/ # Les fichiers sources principaux
|--|- discourse/ # Fichiers de thème Discourse
|--|--|- common/
|--|--|- desktop/
|--|--|- mobile/
|--|- main.css # La feuille de style principale
|--|- main.js # Le point d'entrée JavaScript principal
|--|- sandbox.html # Bac à sable pour le développement local
|- .gitignore
|- discourse-push.js # Script de commit spécial
|- README.md
|- webpack.config.js # Configuration Webpack
|- yarn.lock
Scripts en ligne de commande
De plus, vous avez accès aux commandes suivantes depuis la racine du projet :
# Lancer un serveur de développement sur localhost:8080
# - Prend en charge le rechargement à chaud (livereload)
# - Utilise `/src/sandbox.html` pour vous aider à déboguer localement
npm run dev
# Compiler votre composant dans `/dist`
npm run build
# Compiler votre composant dans `/dist`
# - Puis commit `/dist` dans la branche `discourse`
npm run discourse
Comment cela fonctionne
Une fois que vous avez téléchargé le dépôt et installé les dépendances, il est temps de commencer à développer ! Utilisez npm run dev pour démarrer un serveur de rechargement à chaud sur localhost:8080.
La visite de cette URL chargera le fichier HTML situé dans /src/sandbox.html. Ce fichier n’est pas réellement utilisé dans Discourse ; il est simplement là pour vous aider à développer vos scripts localement (en dehors du contexte de Discourse).
Le point d’entrée principal de Webpack est /src/main.js. À partir de là, vous pouvez importer d’autres scripts et Webpack regroupera tout et les injectera dans les fichiers suivants :
/src/sandbox.html/src/discourse/common/body_tag.html
main.js est compilé et injecté automatiquement dans sandbox.html, mais est injecté manuellement en ligne avec body_tag.html à cause du code suivant :
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Si vous souhaitiez injecter votre script dans un autre modèle, comme after_header.html, vous devriez simplement copier cette balise script dans ce modèle à la place. Cela vous permet de garder le HTML et le JavaScript de ce modèle séparés pendant le développement… mais concaténés lors du déploiement !
Compilation
Lorsque vous compilez avec npm run build, voici ce qui se passe :
- Tout d’abord,
/src/main.jset les dépendances sont regroupés - Ensuite, tous les fichiers de
/src/discourse/sont copiés dans/dist/ - Dans le même temps,
main.jsest injecté en ligne dans tout fichier de modèle contenant :
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Déploiement
Lorsque vous exécutez npm run discourse, le script /discourse-push.js est appelé et effectue les opérations suivantes :
- Tout d’abord, il compile, comme avec
npm run build - Ensuite, il initialise un nouveau dépôt git à l’intérieur de
/dist - Il effectue ensuite un commit de
/distdans la branchediscoursede votre projet (il créera la branche si elle n’existe pas)
Utilisation de la branche discourse
Chacune des URLs relatives
/relative/urls/suivantes est relative à l’URL de base de votre forum, par exemple, https://example.com/relative/urls/
Installer le composant
Installez votre composant en visitant /admin/customize/themes et en choisissant “Importer depuis le web” depuis le dépôt de votre projet, par exemple : https://github.com/mon-incroyable/composant-discourse.
Ensuite, définissez la branche sur discourse. Cela ne fonctionnera pas si vous laissez master, car Discourse essaiera de charger les fichiers non compilés (si cela fonctionne du tout).
Déboguer des fichiers spécifiques au thème sur votre propre hôte
- Installez le Discourse Theme CLI
- Connectez-vous à https://theme-creator.discourse.org
- CD dans ce répertoire, puis exécutez
discourse_theme watch . - Utilisez
https://theme-creator.discourse.orgcomme URL de base- Utilisez votre clé API depuis
theme-creator
- Utilisez votre clé API depuis
Si vous êtes nouveau sur Discourse et souhaitez faire un fork de ce projet, les lectures suivantes pourraient être utiles.