Bearbeitung von @david: Das Theming-System von Discourse unterstützt jetzt mehrere JS-Dateien integriert. Diese Webpack-Methode ist nicht mehr erforderlich.
Hallo! Während ich an meiner Komponente handsfree-discourse arbeitete, stieß ich auf einige Probleme rund um die Dateiverwaltung. Mein Hauptproblem war, dass ich meinen Code über mehrere Dateien aufteilen musste. Das andere Problem bestand darin, dass ich Bibliotheken von Drittanbietern einbinden musste, ohne Administratoren bitten zu müssen, CORS zu aktivieren oder zusätzliche HTTP-Anfragen auszulösen.
Um diese Probleme zu lösen, habe ich discourse-webpack erstellt, eine Vorlage zum schnellen Erstellen von JS-lastigen Komponenten! Zu den Funktionen gehören:
- Lokaler Entwicklungsserver mit Live-Neuladen
- Enthält ein Commit-Skript, um Ihren Quellcode und kompilierten Code in separaten Branches zu halten!
Der Rest dieses Themas erklärt, wie man es verwendet und warum es funktioniert. Ich habe dies gerade für einige andere Komponenten, an denen ich arbeite, getestet, also lass es mich wissen, wenn du auf Probleme stößt oder spezifische Wünsche hast!
Schnelles Erstellen von JavaScript-lastigen Komponenten für deine Discourse-Community, komplett mit einem Commit-Skript, um deinen Quellcode und Build-Code in separaten Branches zu halten, damit du weiterhin schnell liefern kannst!
Installation
Stelle zunächst sicher, dass du NodeJS >= 8 und git lokal auf deinem Rechner installiert hast. Gib dann jede der folgenden Zeilen ein:
# Dieses Repository herunterladen
git clone https://github.com/browsehandsfree/discourse-webpack
# In das Verzeichnis wechseln
cd discourse-webpack
# Abhängigkeiten installieren
npm install
Anschließend musst du die folgenden Einträge in package.json bearbeiten und alle unsere Links durch deine eigenen ersetzen. Insbesondere:
{
name: 'dein-projekt',
repository: {
url: 'git+https://github.com/benutzername/repo'
},
author: '',
bugs: {
url: 'https://github.com/benutzername/repo/issues'
},
homepage: 'https://beispiel.de'
}
Am wichtigsten ist, dass repository.url korrekt ist und mit git+ beginnt. Wenn du npm run discourse ausführst, wird ein Commit erstellt und in dieses Repository gepusht.
Vergiss auch nicht, die about.json-Datei deines Discourse zu konfigurieren, die sich in /src/discourse/about.json befindet.
Entwicklung
Nach npm install erhältst du folgende Verzeichnisstruktur:
discourse-webpack
|- node_modules/ # Abhängigkeiten
|- src/ # Die Hauptquellcodedateien
|--|- discourse/ # Discourse-Themendateien
|--|--|- common/
|--|--|- desktop/
|--|--|- mobile/
|--|- main.css # Die Haupt-Stylesheet-Datei
|--|- main.js # Der Haupteinstiegspunkt für JavaScript
|--|- sandbox.html # Sandbox für die lokale Entwicklung
|- .gitignore
|- discourse-push.js # Spezialisiertes Commit-Skript
|- README.md
|- webpack.config.js # Webpack-Konfiguration
|- yarn.lock
Befehlszeilen-Skripte
Zusätzlich hast du Zugriff auf folgende Befehle aus dem Projektstammverzeichnis:
# Starte einen Entwicklungsserver auf localhost:8080
# - Unterstützt Live-Neuladen
# - Verwendet `/src/sandbox.html`, um dir die lokale Fehlersuche zu erleichtern
npm run dev
# Kompiliere deine Komponente nach `/dist`
npm run build
# Kompiliere deine Komponente nach `/dist`
# - Commitet dann `/dist` in den `discourse`-Branch
npm run discourse
Funktionsweise
Sobald du das Repository heruntergeladen und die Abhängigkeiten installiert hast, kannst du mit der Entwicklung beginnen! Verwende npm run dev, um einen Live-Reload-Server auf localhost:8080 zu starten.
Der Aufruf dieser URL lädt die HTML-Datei, die sich in /src/sandbox.html befindet. Diese Datei wird in Discourse selbst nicht verwendet; sie dient nur dazu, deine Skripte lokal (außerhalb des Discourse-Kontexts) zu entwickeln.
Der Haupt-Einstiegspunkt von Webpack ist /src/main.js. Von dort aus kannst du andere Skripte importieren, und Webpack wird alles zusammenbündeln und in folgende Dateien injizieren:
/src/sandbox.html/src/discourse/common/body_tag.html
main.js wird automatisch kompiliert und in sandbox.html injiziert, wird jedoch manuell inline in body_tag.html eingefügt, aufgrund des folgenden Codes:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Wenn du dein Skript in eine andere Vorlage injizieren möchtest, z. B. after_header.html, kopierst du einfach dieses script-Tag in diese Vorlage. Dies ermöglicht es dir, während der Entwicklung HTML und JavaScript für diese Vorlage getrennt zu halten, sie jedoch beim Deployment zusammenzuführen!
Kompilieren
Wenn du mit npm run build kompilierst, passiert Folgendes:
- Zuerst werden
/src/main.jsund die Abhängigkeiten gebündelt - Dann werden alle Dateien in
/src/discourse/nach/dist/kopiert - Gleichzeitig wird
main.jsinline in jede Vorlagendatei injiziert, die Folgendes enthält:
<script>
<%= compilation.assets['main.js'].source() %>
</script>
Bereitstellen
Wenn du npm run discourse ausführst, wird das Skript /discourse-push.js aufgerufen und führt Folgendes aus:
- Zuerst wird kompiliert, als ob mit
npm run build - Dann wird ein neues Git-Repository innerhalb von
/distinitialisiert - Anschließend wird
/distin dendiscourse-Branch deines Projekts gecommittet (der Branch wird erstellt, falls er noch nicht existiert)
Verwendung des discourse-Branches
Jede der folgenden
/relative/urls/ist relativ zur Basis-URL deines Forums, z. B. https://beispiel.de/relative/urls/
Installation der Komponente
Installiere deine Komponente, indem du /admin/customize/themes aufrufst und „Von Web importieren" wählst, wobei du dein Projektrepository angibst, z. B.: https://github.com/mein-tolles/discourse-component.
Stelle dann den Branch auf discourse ein. Es funktioniert nicht, wenn du ihn bei master lässt, da Discourse versucht, die nicht kompilierten Dateien zu laden (falls es überhaupt funktioniert).
Debugging themenspezifischer Dateien auf deinem eigenen Host
- Installiere die Discourse Theme CLI
- Melde dich bei https://theme-creator.discourse.org an
- Wechsle in dieses Verzeichnis und führe dann
discourse_theme watch .aus - Verwende
https://theme-creator.discourse.orgals Basis-URL- Verwende deinen API-Schlüssel von
theme-creator
- Verwende deinen API-Schlüssel von
Wenn du neu bei Discourse bist und dieses Projekt forken möchtest, könnten die folgenden Beiträge hilfreich sein.