Tutorial: Dein erstes Modul mit dem MMLC programmieren

Bearbeitungszeit: ca. 25 min.

In diesem Tutorial lernst du, wie du per Hand ein eigenes Modul mit der Hilfe des MMLC programmieren kannst. Dazu werden dir alle Schritte gezeigt, die du hierfür kennen solltest. Es ist empfehlenswert, das einmal selber zu machen, um ein generelles Verständnis für die einzelnen Komponenten zu erlangen.

Info: Alternativ gibt es die Möglichkeit, sich die meiste Arbeit von einem Script abnehmen zu lassen. Dafür müsstest du lediglich ./scripts/createModule.sh mc mycompany my-first-module in die Konsole eingeben. Das Script erzeugt dir alle Dateien mit Inhalt und ein fertiges System-Modul, dass du nach deinen Vorstellungen anpassen kannst. Weitere Informationen hierzu findest du unter Modul erstellen mit createModule.sh.

Vorbedingungen #

  • Du hast eine lokale Enwicklungsumgebung aufgesetzt.
  • Du hast eine modified-shop Version 2.0.3.0 oder höher installiert.
  • Du hast den MMLC 1.15.0 oder höher installiert und kannst Module installieren.
  • Du hast einen Code Editor wie VS Code, Atom etc.
  • (Optional aber empfohlen) Du hast git installiert und kannst die einfachen Basics.

Los gehts #

Stelle dir vor du hast eine Firma mit dem Namen "My Company" und diese Firma möchte ein neues Modul mit dem Namen "Mein erstes Modul" entwickeln.

Verzeichnisstruktur erstellen #

Wichtig: Wenn in diesem Tutorial das Root-Verzeichnis von deinem Modified Shop gemeint ist, schreiben wir SHOP_ROOT. In dem Root-Verzeichnis liegt dein ModifiedModuleLoaderClient. Wenn nichts anderes erwähnt wird, werden alle Pfadangaben in diesem Tutorial relativ zu dem Verzeichnis ModifiedModuleLoaderClient angegeben.

Gehe in das Verzeichnis ModifiedModuleLoaderClient, welches du im Root-Verzeichnis deines Shops findest.

Wir erstellen als erstes einen neuen Vendor-Ordner im Verzeichnis ./Modules. Den Ordner nennen wir mycompany. In diesem Vendor-Ordner liegen später alle Module, die du entwickelst. Module von anderen Entwicklern, liegen in deren jeweiligen Vendor-Ordnern, welche sich ebenfalls in dem Verzeichnis ./Modules befinden. Wenn du noch keine Module von einem anderen Entwickler installiert hast, gibt es nur deinen Vendor-Ordner.

Wichtig: Du (oder dein Unternehmen) solltet euch einen Vendor-Ordner-Namen aussuchen, den nur ihr verwendet. Verwende für den Namen nur kleine Buchstaben von a bis z und keine anderen Zeichen. Weitere Informationen findest du unter Naming Convention.

Als nächstes erstellen wir einen neuen Modul-Ordner im Verzeichnis ./Modules/mycompany. Den Modul-Ordner nennen wir my-first-module.

Wichtig: Du kannst dir deinen Modul-Namen frei aussuchen. Am besten ist ein kurzer Name in englischer Sprache. Verwende für den Modul-Namen nur kleine Buchstaben von a bis z und -. Weitere Informationen findest du unter Naming Convention.

Bei dem Modul-Namen handelt es sich um den technischen Namen des Moduls. Das ist nicht der Name, der dem User später angezeigt wird. Den Anzeigename legen wir im nächsten Schritt fest. Die Verzeichnisstruktur sollte jetzt folgendermaßen aussehen:

# Verzeichnisstruktur └── Modules └── mycompany └── my-first-module

moduleinfo.json erstellen #

Nun erstellen wir in dem neuen Modul-Ordner die moduleinfo.json Datei.

Die moduleinfo.json Datei füllen wir mit folgendem Inhalt und vergiss die gescheiften Klammern am Anfang und am Ende nicht:

{ "name": "Mein erstes Modul", "archiveName": "mycompany/my-first-module", "sourceDir": "new_files", "version": "auto", "modifiedCompatibility": [ "2.0.4.2" ] }

Das Feld name können wir frei wählen. Das ist der Anzeigename für den User im MMLC. Das Feld archiveName muss der Vendor-Ordner-Name und der Modul-Ordner-Name getrennt mit einem Slash-Zeichen sein. In unserem Fall ist das mycompany/my-first-module.

Wichtig: Trage im Array modifiedCompatibility die Modified-Shop Version ein, unter der du das Modul entwickelst. Steht hier eine andere Version, zeigt dir der MMLC an, dass das Modul nicht kompatible ist.

Info: Du kannst in dem Array modifiedCompatibility auch mehrere Modified Versionen eintragen, mit denen das Modul kompatible ist. Zum Beispiel: "2.0.4.0", "2.0.4.1", "2.0.4.2". Teste dein Modul mit allen Modifed Versionen, die du hier einträgst, damit der User nicht enttäuscht ist, wenn diese Angaben nicht stimmen.

Nachdem du die Datei gespeichert hast, wird dir das Modul im MMLC unter "Sonstige Module" angezeigt. Gehe in den MMLC, um dir das Modul anzeigen zu lassen.

Info: Damit das Modul unter einer anderen Kategorie angezeigt wird, kannst du in der moduleinfo.json das Feld category hinzufügen. Die möglichen Kategorien findest du unter moduleinfo.json.

Git Repository erstellen (optional aber empfohlen) #

Wenn bis hierhin alles geklappt hat, ist es eine gute Gelegenheit den aktuellen Zwischenstand mit git zu speichern. Erstelle im Verzeichnis ./Modules/mycompany/my-first-module ein neues git-Repository. Das kannst du z. B. über die Konsole machen oder mit einem git-Tool wie SourceTree. Hier das Beispiel mit der Konsole:

> cd ./Modules/mycompany/my-first-module > git init > git add . > git commit -m "feat: Initialer commit"

Tipp: Schau mal auf https://www.conventionalcommits.org/ vorbei. Hier wird dir beschrieben, wie du gute Commit-Messages schreiben kannst. Die Seite erklärt dir auch, wieso wir das Kürzel feat: vor unserer Commit-Message verwendet haben.

Dateien für ein System Modul erstellen #

Wenn du es bis hier geschafft hast, können wir uns an die Arbeit machen, alle nötigen Dateien zu erstellen, die ein Modified Shop für ein System Modul benötigt.

Wichtig: Damit in diesem Tutorial nicht jedes Mal der ganze Verzeichnis-Pfad ./Modules/mycompany/my-first-module ausgeschrieben werden muss, kürzen wir diesen Pfad ab jetzt mit ... ab.

Wie wir in der moduleinfo.json Datei sehen können, haben wir für das Feld sourceDir das Verzeichnis new_files eingetragen. In diesem Verzeichnis befinden sich später alle Dateien, die der MMLC in das Modified Shop System bei einer Installation kopieren soll. Da wir dieses Verzeichnis noch nicht angelegt haben, legen wir nun das Verzeichnis new_files in ./Modules/mycompany/my-first-module bzw. in ... an.

Info: Anstelle von new_files könntest du auch einen anderen Ordner-Namen angeben. Damit alle Module möglichst einheitlich aufgebaut sind, ist die Konvention des MMLC diesen Ordner mit new_files zu benennen.

Für ein System Modul benötigt das Modified System eine PHP Datei in dem Verzeichnis SHOP_ROOT/admin/includes/modules/system/. Damit der MMLC diese Datei in dieses Verzeichnis kopiert, müssen wir das Verzeichnis in .../new_files anlegen. Wir legen also die Verzeichnisstruktur .../new_files/admin/includes/modules/system/ an.

Jetzt können wir anfangen unsere erste PHP HookFile Datei zu erzeugen. Eine HookFile Datei ist eine Datei, die der MMLC bei der Installation eines Moduls in den Shop kopiert und nicht im Ordner SHOP_ROOT/vendor-no-composer landet. Der Dateiname einer HookFile sollte wenn möglich immer mit dem VendorPrefix beginnen. Für den VendorName mycompany bietet sich das VendorPrefix mc an.

Wichtig: Fast alle HookFiles verwenden die Namenskonvention HookFileName die wie folgt definiert ist: VendorPrefix _ ModuleName in snake_case .Dateisuffix. Für weitere Informationen siehe Naming Convention.

Mit diesem Wissen nennen wir die neue Datei mc_my_first_module.php und speichern diese in das eben erstellte Verzeichnis .../new_files/admin/includes/modules/system/. Jetzt sollte deine Verzeichnisstruktur folgendermaßen aussehen:

... ├── moduleinfo.json └── new_files └── admin └── includes └── modules └── system └── mc_my_first_module.php

Die StdModule Klasse #

In die Datei mc_my_first_module.php schreiben wir folgenden PHP Code:

<?php defined('_VALID_XTC') or die('Direct Access to this location is not allowed.'); use RobinTheHood\ModifiedStdModule\Classes\StdModule; require_once DIR_FS_DOCUMENT_ROOT . '/vendor-no-composer/autoload.php'; class mc_my_first_module extends StdModule { public function __construct() { $this->init('MODULE_MC_MY_FIRST_MODULE'); } public function display() { return $this->displaySaveButton(); } public function install() { parent::install(); } public function remove() { parent::remove(); } }

Durch diese Datei wird uns das Module im Shopbackend unter dem Menüpunkt Module > System Module angezeigt. Damit diese Datei mit den wenigen Zeilen Programmcode auskommt, verwenden wir das Library Modul Standard Modul für Modified. Was dieses Modul genau macht und wie du es verwenden kannst ist unter XXX beschrieben.

Für uns ist erst einmal wichtig, dass wir das Modul mit der Konstanten MODULE_MC_MY_FIRST_MODULE initialisieren.

Wichtig: Beschreiben, wie sich die Konstante MODULE_MC_MY_FIRST_MODULE zusammen setzt. Dokumentation in Arbeit ...

Abhängige Module in die moduleinfo.json hinzufügen #

Damit wir das Modul Standard Modul für Modified verwenden können, müssen wir es als Abhängigkeit in unserer moduleinfo.json hinzufügen. Auch brauchen wir das Composer Autoload Library Modul. Beide Module fügen wir durch das require Array in unserer moduleinfo.json hinzu.

"require": { "composer/autoload": "^1.1.0", "robinthehood/modified-std-module": "^0.1.0" }

Danach sollte die gesamte moduleinfo.json wie folgt aussehen:

{ "name": "Mein erstes Modul", "archiveName": "mycompany/my-first-module", "sourceDir": "new_files", "version": "auto", "modifiedCompatibility": [ "2.0.4.2" ], "require": { "composer/autoload": "^1.1.0", "robinthehood/modified-std-module": "^0.1.0" } }

Sprachdatei für das System-Modul erstellen #

User System Modul benötigt noch eine Sprachdatei, damit der User etwas angezeigt bekommt. Die Sprachdatei muss später in dem Verzeichnis SHOP_ROOT/lang/german/modules/system liegen. Damit der MMLC diese Datei in dieses Verzeichnis kopiert, müssen wir das Verzeichnis in .../new_files anlegen. Wir legen also die Verzeichnisstruktur .../new_files/lang/german/modules/system/ an.

Die Sprachdatei bennen wir wieder nach der HookFileName Convention mc_my_first_module.php und speichern diese in das eben erstellte Verzeichnis .../new_files/lang/german/modules/system/. Jetzt sollte deine Verzeichnisstruktur folgendermaßen aussehen:

... ├── moduleinfo.json └── new_files ├── admin | └── includes | └── modules | └── system | └── mc_my_first_module.php └── lang └── german └── modules └── system └── mc_my_first_module.php

Der Inhalt der Datei sieht wie folgt aus:

<?php define('MODULE_MC_MY_FIRST_MODULE_TITLE', 'Mein erstes Modul'); define('MODULE_MC_MY_FIRST_MODULE_LONG_DESCRIPTION', 'Beschreibung ...'); define('MODULE_MC_MY_FIRST_MODULE_STATUS_TITLE', 'Modul aktivieren?'); define('MODULE_MC_MY_FIRST_MODULE_STATUS_DESC', '');

Wenn du es bis hier geschafft hast, könnten wir jetzt bereits unser neues Modul mit dem MMLC installieren. Das Problem ist nur, dass wir bei jeder Änderung, die wir an einer Datei in unserem Ordner new_files machen würden, wieder erneut auf "Installieren" im MMLC klicken müssten. Das macht auf Dauer keinen Spaß.

Aus diesem Grund können wir bei der Entwicklung von Modulen den MMLC so konfigurieren, dass er die Dateien aus dem new_files Ordner nicht in den SHOPT_ROOT kopiert, sondern die Dateien nur verlinkt. Das hat den großen Vorteil, dass jede Änderung, die wir an einer Datei im Ordner new_files machen auch direkt in der entsprechenden Datei in SHOP_ROOT verfügbar wird. Lediglich, wenn wir eine neue Datei im Ornder new_files hinzufügen, müssen wir einmal auf "Installieren" oder auf "Änderungen verwerfen" im MMLC klicken, damit der MMLC auch diese neue Datei in den SHOPT_ROOT verlinkt.

Die Konfiguration hierfür können wir in der /config/config.php deines MMLCs vornehmen. Ändere das Feld installMode auf den Wert link. Jetzt verlinkt der MMLC deine Dateien, anstatt die Dateien zu kopieren.

Deine config.php sollte wie folgt aussehen:

<?php $configuration = [ // ... 'installMode' => 'link', // ... ];

Modul im MMLC installieren #

Nach dem wir alle Dateien für unser Systemmodul erstellt haben und die nötigen Einstellungen im MMLC gemacht haben, können wir unser Modul installieren. Dazu rufen wir wieder den MMLC auf, suchen in der Suche unser Moduel "Mein erstes Modul" und klicken es an. Jetzt können wir auf der Moduldetailseite unser Modul installieren.

Modul im Shopbackend installieren #

Damit wir das Modul nutzen können, müssen wir unser Modul ebenfalls im Shopbackend installieren. Das Modul befindet sich unter Admin > Module > System Module. (Dein Modul erscheint möglicherweise etwas weiter unten in der Liste.)

Modul veröffentlichen #

Herzlichen Glückwunsch, wenn du es bis hierher geschaft hast. Du hast dein erstes Modul für den MMLC programmiert. Es ist nur sehr schade, wenn keiner etwas davon erfährt. Als nächstes kannst du dir anschauen, wie du dein Modul im MMLC veröffentlichst, so das es bei allen im MMLC erscheint, die den MMLC installiert haben.

Tutorial: Dein erstes Modul veröffentlichen