Moduldefinition

Aktualisiert am 10.03.2024 Lesedauer 4 - 5 Min.

Module sind Platzhalter für Code, der beim Export in die Zieldatei eingefügt wird. Sie werden als Text-Datei angelegt (UTF8 ohne BOOM) und können grundsätzlich „alles“ enthalten. Ob das eine Zieldatei mit validem Code erzeugt, liegt in der Hand des Seiten-Erstellers.

Ungültiger Modul-Code kann eine Webseite „abschießen“.

Vor der produktiven Verwendung eines Moduls sollte immer eine Funktionskontrolle in geplanten Szenarien im Zusammenspiel mit anderen Modulen, Funktionen, etc. erfolgen.

Lokal kann ein Test in einer aktiven Umgebung durchgeführt werden, die sich ggf. mit dem Taskmanager beenden lässt.

Modul-Notation

Diese allgemeine Schreibweise wird im Editor z.B. so verwendet:

[modulname "wert" "standardwert" "wert"]

Abgesehen von den rechteckigen Klammern entspricht das der ersten Zeile in der Moduldatei.

modulname "P1" "P2=Standardwert" "P3+" "P+arm=standardwert" "P4=--Standardwert"

In Modulen sollten Vorkehrungen getroffen sein, die ggf. falsche oder fehlende Parameter auffangen. Die Vorgabe von Standardwerten in der Moduldefinition vereinfacht das.

Regeln

  • Für den Modulnamen sind nur Buchstaben und Zahlen zulässig.
  • Der Dateiname muss mit dem Modulnamen identisch sein.
  • Modulparameter werden mit Leerzeichen getrennt
  • Parameter werden in Anführungszeichen eingeschlossen1.
  • Die Schreibweise der Parameternamen in der Notation muss der Schreibweise innerhalb der Modul-Definition entsprechen (A≠a).
  • Die Zuordnung der Parameter erfolgt in der Reihenfolge des Auftretens in der Definition.
  • Von rechts können Parameter wegfallen, Parameter dazwischen können mit „-“ ausgelassen werden.
  • Parameter mit eine „+“ an beliebiger Stelle im Namen werden als Anker an das Modul übergeben.
  • Beginnt ein in der Definition festgelegter Standardwert mit „--“, entspricht das bei der Übergabe einem „-“ (= leer).
    Der Standardwert kann so als Eingabehilfe dienen, z.B. "termin=--dd.mm.yyyy" .

Mit dem Tastenbefehl STRG P („P“arameter ) kann der Inhalt zwischen den nächsten Anführungszeichen rechts vom Cursor selektiert werden. Wird ein Standardwert gefunden, wird der Platzhalter-Name entfernt:

Platzhaltername=WertWert

Der Wert bleibt ausgewählt und kann ggf. direkt überschrieben werden.

Interpretation

  • Befindet sich ausschließlich ein Modul in einer Zeile, wird es wie Code angesehen: In diesem Absatz findet keine Markdown-Übersetzung statt.
  • Die Modulnotation wird „wo sie ist“ durch den Modul-Inhalt ersetzt.
  • Mehrfache Leerzeichen zwischen Parametern werden zu einem zusammengefasst.
  • Ein Parameter mit Standardwert muss mit Anführungszeichen umschlossen sein.
  • Als Parameterwert können Yaml-Variablen und Funktionen und Code übergeben werden.
  • Die Definition der Markdown-Notation muss ausschließlich in der ersten Zeile des Moduls erfolgen.
  • Ein Modul kann keinen oder (theoretisch) beliebig viele Parameter besitzen,

Parameter-Verwendung

Ab der zweiten Zeile beginnt der Modul-Inhalt. Parameter der ersten Zeile werden darin mit §§§Parametername§§§ eingefügt. Diese Schreibweise verhindert Kollisionen zwischen Modulparametern und Yaml-Variablen, die ebenfalls in Modulen verwendet werden können (s. Rang der Auszeichnungen).

Parameter können beliebig oft im Modul verwendet werden, es werden alle Verwendungen ersetzt.

Orte und Rang

In einem Projekt können Module von zwei Orten geladen werden: Aus dem „globalen“ Modul-Ordner, der Projekt-übergreifende Bausteine enthält. Oder aus dem Modul-Ordner des Projekts.

Mit der Projektfunktion Modul-Verzeichnis öffnen werden alle für das Projekt gültige Modul-Verzeichnisse in Explorer-Fenstern geöffnet.

Im Modul-Selektor Einfügen → Modul einfügen… werden die Module beider Ordner angezeigt. Bei gleichnamigen Modulen wird das aus dem Projekt-Modul-Ordner vorgezogen.

Individuelle Anpassungen globaler Module an ein Projekt können durch dieses Verhalten an einer Kopie vorgenommen werden, die im Projekt-Modul-Ordner mit dem gleichen Namen abgelegt wird. Damit können gleichartige Funktionen immer den selben Namen tragen.

Als Modul werden ausschließlich Dateien mit der Endung .html oder .php akzeptiert. Welcher Programm-Code tatsächlich in den Dateien steht, ist dabei ohne Belang. Backups von Modulen in den Modulverzeichnissen, die durch Editoren erzeugt werden (.txt, bak,…) werden aufgrund dieser Einschränkung von der Nutzung ausgeschlossen.

Verwendung

Beim Export wird der Quelltext nach Modulnotationen durchsucht. Gefundene Einträge werden erst im globalen, dann im lokalen Modul-Ordner gesucht. Ein gleichnamiges lokales Modul überschreibt deshalb ggf. ein globales. Wurden Modul-Parameter übergeben, werden diese im geladenen Modul ersetzt, das die Modulnotation im Quelltext ersetzt.

Module werden Bestandteil der Zieldatei. Moduländerungen erfordern die Neugenerierung der Seiten, die es verwenden.

Das ermöglicht die Änderung eines Moduls und das Testen auf einigen Seiten, ohne dass deshalb stets alle Seiten neu erzeugt werden müssen, die es verwenden.

Module sind als „Code-Schnipsel“ innerhalb von Markdown-Abschnitten gedacht, die „seitenweise“ verwandt werden. Auf allen Seiten wiederkehrende Elemente sollten bevorzugt Bestandteil des Layouts sein. Alle Zieldateien können mit Projekte → Projektverwaltung → Projekt neu generieren aktualisiert werden: Das überträgt den aktuellen Stand der Module, des Layouts, etc. in die Zieldateien.

Beispiel-Modul

Das hier für die nachfolgend dargestellten Ergebnisse tatsächlich verwendete Modul »test« erzeugt eine Klasse „info“, mit der die Ausgabe einer schlichten Aufzählung der übergebenen Parameter als Liste umschlossen wird.

test "p1=Vorgabe Parameter 1" "p2=Vorgabe Parameter 2"
<dl class="info">
<dt>Ausgabe von „Test“:</dt>
<ol>
<li><strong>»</strong>§§§p1§§§<strong>«</strong><li>
<li><strong>»</strong>§§§p2§§§<strong>«</strong><li>
</ol>
</dl>

Modulaufruf

Variante 1
[test -] 

Da Parameter definiert sind, muss mindestens ein „leerer“ Parameter übergeben werden. Andernfalls wird eine fehlerhafte Eingabe unterstellt.

Ergebnis:
Ausgabe von „Test“:
  1. »Vorgabe Parameter 1«
  2. »Vorgabe Parameter 2«

Das entspricht der Notation [test - -]

Variante 2
[test "Pos 1"]

Ergebnis:

Ausgabe von „Test“:
  1. »Pos 1«
  2. »Vorgabe Parameter 2«
Variante 3
[test - "Hallo"]

Ergebnis:

Ausgabe von „Test“:
  1. »Vorgabe Parameter 1«
  2. »Hallo«

Das entspricht der Notation [test "" Hallo]

Und wie übergebe ich „nichts“?

„Kein Inhalt“ kann zu undefiniertem Code führen und dennoch erforderlich sein.

Für „richtig leere“ Parameter wird kein Standardwert definiert:

test2 "a=" "b="

Mit dieser gegenüber „test“ veränderten Parameterdefinition liefert „test2“ diese Ausgaben:

Varainte 1 → [test2 -] :

Ausgabe von „Test2“:
  1. »«
  2. »«

Variante 2 → [test2 "Pos 1"] :

Ausgabe von „Test2“:
  1. »Pos 1«
  2. »«

Variante 3 → [test2 - "Hallo"] :

Ausgabe von „Test2“:
  1. »«
  2. »Hallo«

Wie übergebe ich…

Code?

Abgesehen von der Zeichenkonvertierung findet innerhalb der Modulklammern […], wie bei allen mit […] umschlossenen Markdown-Befehlen, keine Markdown-Ersetzung statt. Deshalb kann Code „als Code“ übergeben werden, für die Anführungsstriche muss allerdings eine Ersatznotation gewählt werden, damit es keine Fehlinterpretation der Parameterliste gibt:

Mit Code:
[test "´´Text´´ in Anführungsstrichen." "Für Anführungsstriche wird <em>Accent aigu</em> verwendet."]

Ergebnis:

Ausgabe von „Test“:
  1. »"Text" in Anführungsstrichen.«
  2. »Für Anführungsstriche wird Accent aigu verwendet.«

Anführungsstriche in PHP-Code müssen – wenn mit die Eingabe mit PHP-Code verarbeitet wird – mit \´´ übergeben werden.

Variablen?

Editor-Variablen können wie Werte übergeben werden, denn sie werden innerhalb des eingefügten Moduls ersetzt.

Mit Editor-Variablen:
[test "ca. %%%ERTIME%%% Min." %%%PROGVERS%%% ]

Ergebnis:

Ausgabe von „Test“:
  1. »Lesezeit ca. 5:00 Min.«
  2. »5.4.3«

Funktionen?

Auch Funktionen können Werte übergeben, womit sich die interpretiertes Markdown in einem Modul nutzen lässt.

Mit Funktionen:
[test "$$$ insert  holla $$$" …funktioniert!]$$$ define holla : Dieses sehr einfach gehaltene Beispiel… $$$

Ergebnis:

Ausgabe von „Test“:
  1. »Dieses sehr einfach gehaltene Beispiel…«
  2. »…funktioniert!«

Diese Methode kann komplexe Ergebnisse liefern. Bei derartigen Konstruktionen ist für ein verlässliches Ergebnis ein sehr sorgfältiger Qualitätstest geboten.

1Aus Gründen der Abwärtskompatibilität können zusammenhängende Parameter (Zahl, Wort, Dateipfade) zwar auch ohne Anführungsstriche übergeben werden. Das Umfassen mit Anführungsstrichen ist die bevorzugte Variante.