Direkt zum Hauptinhalt

[ENTWURF] Generico Filter (für Vorlagen) filter_generico

Das Plugin Generico Filter (filter_generico) ermöglicht es, Vorlagen mit Text und Code zentral in der Website-Administration abzulegen und diese dann in Moodle an vielen Orten einzufügen, in denen der HTML-Editor verfügbar ist.

Template erstellen

Templates können von Admins in den Website-Einstellungen zum Plugin erstellt und bearbeitet werden.

Ein Generico Template besteht aus folgenden Feldern:

templatekey

Der Bezeichner eines Templates. Dieser Name solle einzigartig und sprechend sein und den Vorgaben entsprechen, z.B. `qr_code`.

templatename

Dieser Name erscheint im Editor-Plugin (tiny_generico) auf. Er sollte die Funktion des Templates widerspiegeln und nicht zu sehr vom templatekey abweichen, z.B. `QR Code aktuelle Seite`.

templateinstructions

Der Text erscheint im Editor-Plugin nach der Auswahl des Templates. Er liefert eine Beschreibung der Funktion des Templates. Hier können auch die einstellbaren Optionen und Variablen (wenn im Template vorhanden) erläutert werden. Die Anweisungen lassen sich leider nicht als HTML formatieren.

template

Dieser Abschnitt beinhaltet den HTML-Code des Templates. Hier kann nach Belieben gestaltet werden. In diesem Abschnitt sind Variablen verfügbar.

Achtung: Moodle escaped diesen Text nicht und korrigiert keine Fehler wie offen gelassene Tags. Ein fehlerhaftes Template kann die Ansicht der Seite zerstören.

Tipps:

  • Um das Layout zu gestalten, empfiehlt es sich, den Quellcode in einer IDE (wie VSCodium) oder notfalls im Moodle-Tiny-Editor zu verfassen und den Quellcode in das Formularfeld zu kopieren.
  • Es ist sinnvoll, den gesamten Inhalt in ein <div>-Element (bei Textblöcken) oder ein <span>-Element (bei Inline-Text) zu kapseln und dem Inhalt eine Generico-spezifische Klasse zu vergeben. Diese Klasse kann im Moodle-Theme global für Admins z.B. mit einem roten gepunkteten Rand im SCSS gestaltet werden. Damit erkennen Admins Generico-Vorlagen in Kursen leichter, was die Fehlerbehebung erleichtert. Auch lassen sich spätere CSS-Anpassungen dann auf Inhalte von Generico-Templates eingrenzen, um nicht ungewollt das Moodle-Design zu überschreiben.

Beispiel:

<div class="gen-template">
  Hier ist der Inhalt des Templates.
</div>

JavaScript-Code und CSS gehören hier nicht hinwein, sondern in die dafür vorgesehenen Bereiche.

templateend

In Generico-Variablen kann kein nutzerseitiges HTML eingegeben werden. Möchte man vom User bereitgestelltes HTML in Templates verwenden, kann man es zwischen den Beginn und das Ende einer Template einbauen - und dann weiterverarbeiten. In das Feld templateend wird dann das HTML eingetragen, das ein Template abschließt, z.B. abschließende HTML-Tags

Beispiel: ###

templatedefaults (Variablen)

Der Vorteil von Generico besteht darin, Templates generisch passend für viele Kurse zu erstellen. Mit Hilfe von Variablen können die Vorlagen dann angepasst werden. Generico-Variablen haben die Syntax @@variablenname@@. 

  • Kursvariablen, Uservariablen: Man kann aus der Moodle-Datenbank zum aktuellen Kurs oder zum eingeloggten User Infos anzeigen lassen, beispielsweise:
    • @@USER:firstname@@ - zeigt den Vornamen des eingeloggten Users an.
    • @@COURSE:fullname@@ - zeigt den kompletten Titel des aktuellen Kurses an.
    • Diese Variablen müssen nicht definiert werden und können im Template verwendet werden.
  • Details zur Datenbankstruktur finden sich unter https://www.examulator.com, etwa in den Tabellen users oder courses und darin verfügbaren Feldern.
  • Nutzerdefinierte Variablen: Im Template lassen sich auch eigene Variablen definieren, etwa @@lieblingsfarbe@@. Wird ein Template per Editor eingefügt, zeigt das Formular definierte Variablen zum Ausfüllen an.
    • Variablen werden zeilenweise definiert und per Komma getrennt:
      Lieblingsessen=Pizza,
Farbe=blau|grün|rot
    • Frei einzutragende Variablen werden wie in Zeile 1 definiert. Wird im Formular kein Wert eingetragen, wird der Standardwert (im Fall des Lieblingsessens ist es "Pizza" angenommen.
      Achtung: User sollten keine Anführungszeichen `"` eintragen. Diese brechen die Syntax und führen zu Fehlern. HTML wird in Variablen nicht ausgewertet.
    • Variablenwerte, bei denen eine Wahl aus vorgegebenen Werten angeboten wird, werden durch ein Pipe `|` getrennt. User sehen im Formular ein Drop-Down-Feld.
      Achtung: Nach dem Einfügen der Vorlage kann der Wert jedoch nach Belieben (auch durch unsinnige Werte) ersetzt werden.

templatescript

...In diesem Teil wird das JavaScript des Templates erstellt. Es wird nach dem erfolgten Laden der Seite ausgeführt.

templatestyle

In diesem Teil wird das Styling des Templates mit CSS vorgenommen.

Tipps:

  • Es ist sinnvoll, den gesamten Inhalt in ein <div>-Element (bei Textblöcken) oder ein <span>-Element (bei Inline-Text) zu kapseln und dem Inhalt eine Generico-spezifische Klasse zu vergeben. Diese Klasse kann im Moodle-Theme global für Admins z.B. mit einem roten gepunkteten Rand im SCSS gestaltet werden. Damit erkennen Admins Generico-Vorlagen in Kursen leichter, was die Fehlerbehebung erleichtert. Auch lassen sich spätere CSS-Anpassungen dann auf Inhalte von Generico-Templates eingrenzen, um nicht ungewollt das Moodle-Design zu überschreiben.

Beispiel:

<div class="generico-template generico-warnhinweis">
  Hier ist der Inhalt des Templates.
</div>

Ein solches Element lässt sich mit CSS dann gezielt gestalten, ohne andere Elemente zu beeinflussen:

...generico-warnhinweis {
  border-style: dotted; 
  }

Falls doch moodle-eigene Klassen umgestaltet werden sollen, sollte dies vorher auf einer Testinsatz ausprobiert werden. Es ist sinnvoll, das Template geöffnet zu haben, um die Änderung rückgängig zu machen, falls man versehentlich Teile der Seite unbrauchbar macht.

dataset

Hier werden Datenbankabfragen als SQL-Anweisungen eingetragen. Es lassen sich Platzhalter als `?` definieren. Die Platzhalter werden nacheinander in den `datasetvars` definiert. Jeder Platzhalter, auch wenn er mehrfach vorkommt, muss einzeln in den datasetvars definiert werden.

Beispiel:

SELECT 
    c.id AS course_id,
    c.fullname AS course_name,
    cat.name AS category_name
FROM {course} c
JOIN {course_categories} cat ON c.category = cat.id
WHERE c.id = ?; -- dies ist der Platzhalter - er wird in den datasetvars durch @@COURSE:id@@ ersetzt

Tipp: 

  • Manche Abfragen belasten das System stark. Es sollte vorher getestet werden, wie aufwändig eine Abfrage ist. Die SQL-Abfrage lässt sich vorher mit dem Plugin configurable reports testen. Anstelle der Platzhalter `?` existieren dort jedoch andere Platzhalter wie ``%%USERID%%`, %%COURSEID%% oder indem manzu Testzwecken  feste Werte in die Abfrage einbaut, etwa `userid=2`...

datasetvars

Alle im dataset vorhandenen Platzhalter (`?`) müssen in der richtigen Reihenfolge in den datasetvars definiert werden, z.B. `@@COURSE:id@@;@@COURSE:id@@;@@USER:id@@`... 

Achtung:

  • Falls ein Platzhalter in dem Kontext nicht verfügbar ist, wird das Laden der Seite mit einem PHP-Fehler abgebrochen! Beispiel: Fragt man Daten zum aktuell geöffneten Quiz (aus dem URL-Parameter) ab und wird das Template an einer Stelle geladen, an dem es keinen URL-Parameter für das Quiz gibt, lädt die Seite nicht mehr. Es ist sinnvoll, solche Abfragen vor dem Endnutzer im Editor-Formular zu verbergen.

Template löschen

Es existiert keine Funktion zur Löschung. Templates werden gelöscht, indem alle Formularfelder geleert werden und das Template gespeichert wird. Befindet sich das Template in Verwendung, wird nach dieser Löschung im Kurs an Stelle des Templateaufrufs nichts angezeigt.

Tipp: Ein leeres Template (nur mit einem Template key versehen) kann als Bundle importiert werden, um alle Felder des Formulars schnell zu leeren. Nach dem Löschen des Keys im Formular und dem Speichern ist das Template gelöscht.

Template einfügen

Templates können entweder händisch durch die Eingabe der Template-Namen oder über den dazugehörigen Editor (tiny_generico) per Formular eingefügt werden. Das Editor-Plugin unterstützt bei der Eingabe, wenn das Template Variablen oder Optionen enthält.

Einschränkungen

  • Der Textfilter eignet sich nicht für Texte, die per E-Mail versendet werden, wie z.B. Forenbenachrichtigungen. Dort wird stattdessen nur die Filter-Syntax angezeigt.
  • Generico bietet keine Versionierung an. Es empfiehlt sich, die Versionierung mit externen Werkzeugen zu erledigen.

Versionierung

Backups

In den Template-Einstellungen lassen sich keine Versionen verwalten. Ein manuelles Backup ist über den Bundle Button möglich. Dann wird eine JSON-formatierte .txt Datei heruntergeladen, mit der sich (fast) alle Einstellungen eines Templates herunterladen lassen.

Vor dem Bearbeiten eines Templates, ist es ratsam, ein manuelles Backup zu erstellen. Bei Fehlern und Problemen kann das Backup schnell wiederhergestellt werden.

Wiederherstellung

Um ein Template auf eine vorherige Version wiederherzustellen, kann man einen .txt Export auf den Bundle Button ziehen. Das Formular wird mit den Werten der .txt Datei überschrieben. Nach einem Speichern des Formulars, ist diese Version in Kraft.

Bei ungültigen .txt Dateien meldet die Seite keinen Fehler. Um manuell festzustellen, ob der Import funktioniert hat, kann man vor dem Import einen Teil des Formulars (z.B. die Versionsinfo) löschen. Ist nach dem Drag-and-Drop der Bundle-Datei das Feld wieder gefüllt, hat der Import funktioniert. 

Warnung und generelle Tipps

  • Vorlagen sollten gründlich getestet werden, am besten auf einem Staging-System, das eine Kopie des aktuellen Moodles beinhaltet, um die Auswirkungen des Templates zu beurteilen. Dies gilt insbesondere dann, wenn JavaScript Code oder CSS verwendet werden.
  • Die Bearbeitungsseite der Vorlage sollte beim Testen immer geöffnet bleiben. Falls man Fehler im Template erzeugt, die z.B. das Bearbeiten der Moodle-Seite stören, lässt sich der Code aus dem Template in der Website-Administration entfernen, damit die Seite wieder funktioniert.
  • Auch wenn Templates nicht auf einer Seite direkt eingebunden werden, können sie gelegentlich Probleme an unerwarteten Stellen verursachen.
  • Werden Datasets (SQL-Anweisungen) verwendet und fehlen die richtigen Parameter, gibt Moodle einen PHP-Fehler aus, was die Anzeige der gesamten Seite stört.

Nachfolge-Plugin generico two

Das Plugin genericotwo befindet sich in Entwicklung. Es hat noch nicht die gleiche Reife erreicht, wie das ursprüngliche filter_generico, bietet jedoch einige interessante Funktionen:

  • Als Template-Syntax wird Moodles Mustache genutzt (siehe Beschreibung unter https://moodledev.io/docs/5.3/guides/templates). Damit lassen sich z.B. Datensätze mit mehreren Zeilen ohne JavaScript zeilenweise als Tabellen ausgeben.
  • Der Template-Editor bereitet den Code mit Syntax Highlighting optisch übersichtlicher auf.
  • Im Template-Editor findet sich eine Vorschau, mit der sich die Templates testen lassen.
  • Einfache ältere Generico Templates können zu Generico Two migriert werden.

Derzeit gibt es noch einige Einschränkungen:

  • Die Migration längerer oder komplexerer Templates des ursprünglichen Generico ist noch fehlerhaft. 

GitHub Repository: https://github.com/justinhunt/moodle-filter_genericotwo

nach oben