[x]-Modul programmieren

Aneamal hat einen umfangreichen Funktionsumfang, doch da der Fantasie kaum Grenzen gesetzt sind, leistet der Kern des Aneamal-Konverters bei Weitem nicht alles, was denkbar ist. Du kannst ihn aber um Zusatzmodule erweitern, um beispielsweise einen Besucherzähler oder eine Kommentarfunktion zu realisieren.

Diese Seite richtet sich an Programmierer mit PHP-Kenntnissen, die selbst neue [x]-Module basteln möchten, und erklärt, wie man das macht. Ein solches Modul erhält einen Namen wie kommentare, saftpresse oder ray, welcher beim Verwenden des Moduls im [x]-Element nach einem Bindestrich angegeben wird:

[x-ray]->die-knochen-meiner-hand.jpg

Platz fürs Zusatzmodul

Das Modul wird in einem Unterordner des aneamal-Verzeichnisses abgelegt, der x-ray heißt, wenn der Name des Moduls ray ist. Die Hauptdatei darin muss index.php heißen. Insgesamt lautet der Dateipfad der Hauptdatei also /aneamal/x-ray/index.php. Beachte, dass der Dateipfad immer kleinbuchstabig ist. Weitere Dateien werden nicht erwartet, können aber nach Gusto des Entwicklers im gleichen Ordner angelegt werden.

Aufbau von index.php

Die Hauptdatei des Zusatzmoduls sollte so aufgebaut sein:

Das Modul soll also mit return eine unbenannte function an den Aneamal-Konverter geben, in dem das Modul seine Wirkung entfaltet. Dafür übergibt der Aneamal-Konverter der Funktion Informationen in Form eines Felds (array), hier beispielhaft $_ genannt.

Parameter der unbenannten Hauptfunktion

Das vom Aneamal-Konverter ans Zusatzmodul übergebene Feld, hier beispielhaft $_ genannt, enthält mehrere Elemente. Hauptsächlich handelt es sich um Pfadangaben, von denen du kaum je alle benötigen wirst. Es wird für dich darauf ankommen, die für deine Zwecke geeigneten Informationen zu wählen:

$_[0]

array, Pfadinformationen, im Folgenden erläutert

$_[0][0]

string, Pfad der Zieldatei genau wie im Dokument nach [x-…]-> angegeben

$_[0][1]

string, absoluter Pfad zur Zieldatei auf dem Server, wie man ihn in PHP nutzen kann, um auf die Datei zum Beispiel mit file_get_contents und file_put_contents zuzugreifen; null wenn es keinen solchen Pfad gibt, weil beispielsweise eine Daten-URI angegeben wurde

$_[0][2]

string, URL zur Zieldatei, wie man sie in HTML verwenden kann, um mit <a href='…'> einen Link zur Datei zu setzen; Sonderzeichen sind noch nicht für den Einsatz in HTML kodiert, wofür du die PHP-Funktion htmlspecialchars nutzen kannst

$_[0][3]

string, absoluter Pfad zum Aneamal-Root-Verzeichnis auf dem Server; der Pfad hat keinen Schrägstrich am Ende

$_[0][4]

string, URL zum Aneamal-Root-Verzeichnis relativ zur Domain; die URL hat keinen Schrägstrich am Ende; Sonderzeichen sind noch nicht für den Einsatz in HTML kodiert, wofür du die PHP-Funktion htmlspecialchars nutzen kannst

$_[1]

string, ein optionales Argument, das im Aneamal-Dokument nach einem Doppelpunkt in [x-…:ARGUMENT]-> angegeben werden kann

$_[2]

string, URL zu jenem Verzeichnis, in dem dein Zusatzmodul liegt, relativ zur Domain; die URL hat keinen Schrägstrich am Ende; Sonderzeichen sind noch nicht für den Einsatz in HTML kodiert, wofür du die PHP-Funktion htmlspecialchars nutzen kannst

$_[3]

string, URL relativ zur Domain zu jenem Verzeichnis, in dem die Aneamaldatei liegt, in welcher das Modul mit [x-…]-> gerade verwendet wird; die URL hat keinen Schrägstrich am Ende; Sonderzeichen sind noch nicht für den Einsatz in HTML kodiert, wofür du die PHP-Funktion htmlspecialchars nutzen kannst

Im Beispielmodul könnte das übergebene Feld beispielsweise diesem PHP-Code entsprechen:

Beispielmodul: audio

Als Beispiel habe ich ein Modul programmiert, mit welchem man Audiodateien einbinden kann:

Diesen Code speicherte ich als /aneamal/x-audio/index.php ab.

Das Modul zeigt in modernen Webbrowsern Bedienelemente zum Abspielen einer Audiodatei an. Browser, die das nicht können, sollten hingegen einen Link zum Herunterladen zeigen. Probieren wir es aus! Grün ist hinterlegt, was in einer Aneamaldatei steht, um das Modul zu nutzen. Gelb ist hinterlegt, wie das im Webbrowser angezeigt wird:

[x-audio]->musik/march.mp3
Ein Ausschnitt aus *March*
Komponist: HienTau->https://www.youtube.com/channel/UCVVpRZwgz5fO-TORkZvvreQ

Bitte beachten

Ein Modul soll problemlos umbenannt werden können

Baue den Namen des Ordners, in dem dein Zusatzmodul liegt, nicht fest in dein Modul ein. Verwende stattdessen den übergebenen Parameter $_[2], wenn du einen Link zu Dateien im Modulordner benötigst. Hintergrund: Wenn du dein Zusatzmodul an jemanden weitergibst, der schon ein anderes Modul mit dem gleichen Namen nutzt, braucht er nur deinen Ordner umzubenennen, um beide Module nutzen zu können.

Verschiedene Module sollen parallel funktionieren

Damit es zu keinen Konflikten bei Namen von Funktionen und Konstanten zwischen verschiedenen Zusatzmodulen kommt, solltest du einen wirklich individuellen namespace am Anfang deiner PHP-Datei(en) verwenden.

Dein Modul muss UTF-8-kodierten HTML-Code ausgeben

Was deine Hauptfunktion zurückgibt, wird so in den HTML-Code von Webseiten eingebaut. Es sollte sich also um gültiges HTML handeln und die Zeichenkodierung UTF-8 genutzt werden. UTF-8 ist nicht nur Aneamals Standardzeichensatz, sondern auch die mit Abstand am weitesten verbreitete Kodierung im weltweiten Netz. US-ASCII ist auch fein – das ist nämlich eine Teilmenge von UTF-8.

Dein Modul soll sicher sein

Mach keinen Quatsch. :)