diff --git a/README.md b/README.md index 7ee9879..ceba5ef 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,22 @@ -# Entwicklungsvorlage für Plugins +# Matomo Tracking Plugin für JTL-Shop -Für Fragen zur Nutzung des Plugins kann man sich an mich per E-Mail wenden: +## Informationen -- Dennis Heinrich +> **Das Plugin ist nicht für den Produktiveinsatz freigegeben, da es noch nicht vollständig getestet wurde. Es wird empfohlen, das Plugin nur in einer Testumgebung zu verwenden.** -## Mitgelieferte Features +Dieses Plugin ermöglicht es, Matomo Tracking in JTL-Shop zu integrieren. Es nutzt die HTTP-API von Matomo, um die Daten an den Matomo-Server zu senden. Das Plugin ist so konzipiert, dass es einfach in JTL-Shop integriert werden kann. So werden Umsatz-Ereignisse, Produktansichten und Warenkorb-Ereignisse an Matomo gesendet. -Diese Vorlage kommt mit folgenden Technologien: - -- Bootstrap Klasse -- Webpack Bundler - - TypeScript - - SCSS Loader - - TailwindCSS - -### Was ist Webpack? - -Webpack ist ein Bundler, der alle Dateien (JavaScript, CSS und ggf. Bilder) in eine einzelne Datei -bündelt: Das Resultat ist das Bundle. Dabei werden alle SCSS Dateien in CSS Dateien kompiliert. -Der Vorteil darin ist, dass Anfragen an den Shop gespart werden und die Seitengeschwindigkeit erhöht wird. - -### Was ist TailwindCSS? - -TailwindCSS ist ein CSS-Framework, das es ermöglicht, CSS direkt im HTML zu schreiben (ohne dabei Inline) -zu sein. Es ist sehr flexibel und kann mit SCSS kombiniert werden und ist eine moderne Alternative zu -überladenen CSS-Frameworks wie Bootstrap, denn Tailwind kompiliert ausschließlich die verwendeten Klassen -und nicht das gesamte Framework in das Webpack Bundle. - -Wenn man mit dem Umgang nicht vertraut ist, kann das einfach ignoriert werden, denn wie bereits erwähnt wurde, -werden nur benutzte Klassen kompiliert und erhöht nicht die Dateigröße vom Webpack Bundle. - -### Was ist TypeScript? - -TypeScript ist eine Programmiersprache, die auf JavaScript basiert. Sie bietet die Möglichkeit, Typen zu definieren, -was die Entwicklung qualitativ aufwerten kann. Statt .js Dateien werden .ts Dateien verwendet, die dann in .js Dateien -kompiliert werden. +## Voraussetzungen -TypeScript zu schreiben ist optional und kann auch ignoriert werden, denn man kann auch reines JavaScript in die Datei -schreiben. Dennoch muss nach dem Ändern der Datei das Webpack Bundle neu gebaut werden. +- NodeJS mit `npm` oder `pnpm` +- JTL Shop auf 5.3.1 oder höher +- PHP 8.0 oder höher ## Entwicklung starten -### Namespace anpassen - -Das Plugin benötigt einen einmaligen Namespace. Dieser muss in auch der Datei `./plugin.xml` angepasst werden. -Die einfachste Lösung ist, im gesamtem Plugin nach `plugin_test` zu suchen und durch den gewünschten Namespace zu -ersetzen, z.B. `meine_firma_plugin_fuer_funktion_xy`. Gängige Praxis ist es, ein Präfix zu verwenden, das allen -eigenen Plugins vorangestellt wird, z.B. `meine_firma` und anschließend der technische Name des Plugins, z.B. `plugin_fuer_funktion_xy`. +Hier sind einige Befehle, die für die Entwicklung des Plugins hilfreich sind. -### README.md anpassen - -Die Datei `README.md` ist die Datei, die auf GitHub und im Plugin unter dem Tab "Dokumentation" angezeigt wird. -Sie sollte mit Informationen zum Plugin angepasst werden, damit Nutzer die Funktion des Plugins verstehen. - -### Webpack Bundle bauen - -Damit das Webpack Bundle gebaut werden kann, müssen die Projekt-Voraussetzungen erfüllt sein. Dann muss die -Kommandozeile im Ordner (`./frontend/webpack`) geöffnet werden. +### Webpack Befehle Um die Abhängigkeiten für Webpack zu installieren, müssen folgende Befehle ausgeführt werden: ```shell @@ -64,10 +24,6 @@ npm install # Für Nutzer, die npm nutzen pnpm install # Für Nutzer, die pnpm nutzen ``` -Wenn nun entwickelt wird, muss bei sämtlichen Änderungen das Webpack Bundle neu gebaut werden. Dafür gibt es zwei -verschiedene Befehle: einen um das Bundle einmalig zu bauen und einen um das Bundle bei Änderungen automatisch neu -zu bauen. Bei der automatischen Variante muss die Kommandozeile offen bleiben. - Für das einmalige Bauen des Bundles: ```shell npm run build # Für Nutzer, die npm nutzen @@ -80,24 +36,9 @@ npm run watch # Für Nutzer, die npm nutzen pnpm run watch # Für Nutzer, die pnpm nutzen ``` -### Veröffentlichung eines Plugins (Workflow) - -Wenn das Plugin fertig entwickelt wurde, kann es veröffentlicht werden. Dazu gehört u.a. das abschließende -Bauen des Webpack Bundles und das Erstellen eines ZIP-Archivs. Um dem Entwickler eine -einfache Möglichkeit zu geben, Versionen zu erstellen und zu veröffentlichen, gibt es ein GitHub-Workflow. - -Der Workflow wird automatisch nach einem Push auf GitHub ausgeführt, wenn ein neuer Tag mit Git erstellt wurde. So kann man -wenn man eine neue Version erstellt hat, einen Tag mit der Versionsnummer erstellen und alle Schritte werden automatisch -ausgeführt. Das Plugin bekommt dann unter dem Tab "Releases" auf GitHub einen Eintrag mit der Versionsnummer und dem Link zum -Download des fertigen Plugins. Das erstellen eines Tags kann mit folgendem Befehl ausgeführt werden: +### Veröffentlichung des Plugins (Workflow) ```shell git tag 1.0.0 # Für die Version 1.0.0 git push --tags # Tags auf GitHub hochladen -``` - -## Voraussetzungen - -- NodeJS mit `npm` oder `pnpm` -- JTL Shop auf 5.0.0 oder höher -- PHP 7.4 oder höher \ No newline at end of file +``` \ No newline at end of file