Handbuch für Entwickler

So findest du dich im Quellcode zurecht und setzt deine erste Änderung lokal um.

Doku · Dateireferenz

Entwicklungsumgebung

Verwende einen sauberen 1.0.0-Quellbaum und Perl 5.34 oder neuer. Starte den Chat über tools/run-local.sh mit einer frischen lokalen Konfiguration. Der Webserver verwendet den Interpreter aus der ersten Zeile von cgi-bin/chat.pl. Prüfe ihn unabhängig vom Perl deiner Shell.

perl -v
perl -c cgi-bin/chat.pl

Prüfe Änderungen an der Oberfläche mit zwei Testkonten in getrennten Browserprofilen. Teste die Desktop- und Mobilansicht, einen Verbindungsabbruch und die betroffenen Formulare.

Perl in GTChat

my deklariert eine lexikalisch gebundene Variable. Skalare wie $chat enthalten Werte oder Referenzen. \@items und \%fields erzeugen Referenzen auf Arrays und Hashes. $record->{name} liest einen Hash-Eintrag. Bei $service->read($name) ist das Objekt der erste Parameter. Typisch für Methoden ist my ($self, $name) = @_;.

use strict;
use warnings;

sub public_room_names {
    my ($rooms) = @_;
    return [map { $_->{name} } grep { !$_->{closed} } @$rooms];
}

grep filtert die Liste und map bildet die übrigen Einträge auf die Raumnamen ab. Die eckigen Klammern geben eine Array-Referenz zurück. Das Beispiel setzt eine bereits autorisierte Liste voraus. Für echte Anfragen ist die Berechtigungsprüfung des jeweiligen Dienstes zuständig.

Von der Anfrage zur Antwort

  1. cgi-bin/chat.pl richtet die Laufzeit ein und erzeugt das zentrale Anwendungsobjekt.
  2. Sources/RequestContext.pm verwaltet Eingaben und Identität pro Anfrage. Persistente Worker bearbeiten Anfragen verschiedener Benutzer. Flüchtige Zustände gehören daher in diesen Kontext.
  3. Kernaktionen und registrierte Plugins prüfen die Anfrage und rufen den zuständigen Dienst oder das Repository auf.
  4. Die Template-Engine erzeugt HTML. Die Übertragungsschicht sendet versionierte Nachrichtenereignisse an den Browser.

Beginne bei einer Formularaktion oder beim Skript eines Buttons und folge der Zuordnung zum Handler und zur Ausgabe. Einstellungen der Administration nutzen etwa Templates unter Templates/admin/ und den Handler Plugins/Administration/Settings.pm.

Dateien, Zustände und Repositories

Sources/ enthält Dienste, Richtlinien und Speicheradapter. Repositories übernehmen Dateizugriffe. Erweitere beim Ändern dauerhaft gespeicherter Daten die zuständigen Dienste und Repositories, damit Dateiidentität, Sperren und Veröffentlichung zusammenpassen.

Settings.static.dat verdrahtet Aktionen und Erweiterungen. SiteSettings.default.dat liefert Vorgaben für Neuinstallationen. Änderbare Einstellungen stehen in Variables/site-settings.json. Die Dateireferenz nennt Aufgaben und Einstiegspunkte der einzelnen Dateien.

Plugins und Erweiterungspunkte

Orientiere dich an einem mitgelieferten Modul des aktuellen Builds. Ein Modul wie Plugins/CommandHandlers/TextCommands.pm gibt einen gesegneten Hash mit command_handlers zurück, der Befehlsnamen mit Handler-Referenzen verbindet. Die Konfiguration ordnet Befehle unter custom_command_handlers einem Modul zu. Öffentliche Aktionen verwenden die Aktionsregistrierung. Lies das Modul und den zugehörigen Eintrag in Settings.static.dat gemeinsam.

Gib den unterstützten GTChat-Build an, nutze eindeutige Befehle und liefere eigene Übersetzungen und Templates mit. Behandle Anfrageparameter als Benutzereingaben. Ermittle Konto, Raum und Rechte über die bestehenden Schnittstellen. Prüfe erfolgreiche und abgewiesene Anfragen sowie einen erneuten Verbindungsaufbau.

Alte Plugins mit ausführbaren Client-Code-Strings müssen angepasst werden. 1.0.0 verwendet bekannte Client-Aktionskennungen und typisierte Ereignisse. Für UI-Änderungen stehen CHAT_EVENT und die vorhandenen Client-Aktionen bereit.

Der erste eigene Befehl

  1. Lege das Modul unten in deiner lokalen Testinstallation als cgi-bin/Plugins/CommandHandlers/Hello.pm ab.
  2. Ergänze hello => 'plugindir::CommandHandlers/Hello.pm' unter custom_command_handlers in Settings.static.dat. Verwende für dieses lokale Beispiel 'command.hello' => 1 in den Standardrechten derselben Datei. Prüfe vorhandene Befehlsrechte, falls die Installation eigene Einstellungen hat.
  3. Führe perl -c cgi-bin/Plugins/CommandHandlers/Hello.pm aus, starte den lokalen Server und melde dich als Mitglied an. Gib /hello ein. Die Antwort soll nur in deiner Sitzung erscheinen. Prüfe eine zweite Browsersitzung und den Raumverlauf.
package GT_Chat::Plugins::Hello;
use strict;
use warnings;

return bless({
    command_handlers => { hello => \&hello_handler },
});

sub hello_handler {
    my ($plugin, $chat, $command, $arguments) = @_;
    my $user = $chat->{current_user};
    my $message = $chat->createOutput({
        template => 'text',
        name => $user->{name},
        nick => $user->{nick},
        color => $user->{color},
        text => $chat->toHTML('Hello from your GTChat plugin.'),
    });
    return [$message->restrictToCurrentUser];
}

Das zurückgegebene Objekt meldet den Handler an. Vor dem Aufruf prüft der Server die Berechtigung und übergibt den aktuellen Anfragekontext. Der Handler gibt eine Array-Referenz mit Ausgabedatensätzen zurück. restrictToCurrentUser bindet die Antwort an das aktuelle Konto und bei verfügbarer Sitzungskennung an die Sitzung. Veröffentlichte Plugins sollten übersetzte Texte verwenden.

Templates, Übersetzungen und Darstellung

INCLUDE bindet gemeinsame Fragmente ein. T lädt übersetzte Texte, und GET_HTML maskiert Werte für HTML-Ausgabe. Verwende für URLs und JavaScript-Strings die jeweiligen Tags aus vergleichbaren Templates. Eine ausgeblendete Schaltfläche ersetzt keine Rechteprüfung im Handler.

Pflege deutsche und englische Übersetzungen gemeinsam. Die gemeinsame Gestaltung steht in www/style.css. Prüfe Lesbarkeit, Links und Formularfelder in heller und dunkler Darstellung sowie mit den verwendeten Paletten.

Darstellung
Darstellung

Übertragung und Client-Ereignisse

Der Browser empfängt versionierte JSON-Pakete. Auf der SSE-Verbindung heißt das Ereignis chat. Polling und Dokument-Streaming verwenden dieselben Ereignisdaten. Raumverlauf, private Nachrichten, Mitgliederliste, Moderation, Darstellung und Verbindungsabbruch haben eigene Handler.

Veröffentliche zusammenpassende Templates und Browserdateien. Prüfe einen normalen Raumbeitrag, eine private Nachricht und den Wiederaufbau der Verbindung. Die Entscheidung über Absender- und Empfängerrechte bleibt beim Server.

Privates Gespräch
Privates Gespräch