Moduldefinition

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.

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"

Parameter-Verweis

Bereits eingelesene Parameter können innerhalb der Parameterliste mit §§x referenziert werden, wobei x die Position in der Parameterliste definiert. Die Referenz bezieht sich auf den im Markdown festgelegten Parameter-Inhalt.

Das ermöglicht eine übersichtlichere und kürzere Schreibweise bei Modulen, die gleiche Einträge für verschiedene Parameter haben können, doch gleichermaßen unterschiedliche.

Beispiel

[modulname "Heinz" "Willi" "§§2" "§§3"]

Was passiert

Parameter Nr.	Übergebener Wert	Ausgabe
1	Heinz	Heinz
2	Willi	Willi
3	§§2	Willi
4	§§3	§§2

Parameter 4 verweist auf Parameter 3, der allerdings nur bei der Auswertung von Parameter 3 den Inhalt von Parameter 2 erhält.

%id%

Für eindeutige IDs, die im Allgemeinen lediglich innerhalb des Moduls relevant sind, kann mit %id% eine achststellige GUID erzeugt werden, mit der eine ID-Basis zwecks Eindeutigkeit erweitert wird.

Aus dem Parameter t%id% wird damit (zum Beispiel) t12345678, bei der nächsten Ausgabe (zum Beispiel) tA1B2C3D4. Bei jedem Export der Arbeitsdatei wird %id% neu generiert.

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" .

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.

Parameter-Verweis

In der Modul-Notation kann mit §§1..x ein in der Notation vorhandener Parameter referenziert und damit die Parameter-Übergabe vereinfacht werden. Das erlaubt die standardisierte Zuweisung eines Parameter-Wertes für weitere Parameter, die meistens identisch, aber manchmal anders sein können.

Die Zählung beginnt bei „1“ für den ersten Parameter nach dem Modulnamen. Eine Referenz darauf kann für alle anderen Parametern mit „§§1“ erfolgen.

Beispiel

[imgmag "href=datei" "Alt=Keine Bildbeschreibung verfügbar" "Titel=§§2" "ID=imag%id%" "css=right" "Untertitel=§§2"]

In diesem Modul wird der Parameter 2 (Alt-Text für ein Bild) als Default für den Titel und den Inhalt einer Textbox unter dem Bild vorgeschlagen. Dieser kann wahlweise mit einem anderen Text ersetzt oder für den „Untertitel“ kann auch „§§3“ verwendet werden, wenn der „Titel“ ein vorteilhafterer Text für die Textbox wäre.

Vorsicht:

Bei Zirkelverweisen hat kein Parameter einen Inhalt!

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 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]

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:50 Min.«
2. »5.5.1«

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.