kivitendo/doc/help_system.md @ e87d47c3
Entwicklerdokumentation kivitendo-Hilfesystem
Im Layout wird immer ein Hilfe-Link gerendert. Dieser öffnet ein Popupfenster und ruft darin die Action Help/show auf. Ihr wird eine Kontextinformation übergeben, mit der der Controller entscheiden kann, welche Hilfeseite angezeigt wird. Diese Kontextinformation wird automatisch aus dem aktuellen Controller und der aktuellen Action abgeleitet, kann aber im Controller überschrieben werden.
Popup-Fenster
Hilfetexte werden in einem Popup-Fenster angezeigt. Das Link-Target für dieses Popup lautet _kivitendo_help.
Kontextinformationen
Die Kontextinformationen werden normalerweise aus dem aktuellen Controller und der aktuellen Action erzeugt. Sie bestehen aus zwei Elementen, die durch einen / voneinander getrennt werden. Sie haben das Format controller/action.
Jedes Element der Kontextinformationen darf dabei nur aus den folgenden Zeichen bestehen:
- Buchstaben
a-zundA-Z - Ziffern
0-9 - Die Zeichen
_und-
Speichern des aktuellen Controllers und der aktuellen Action
Um Kontextinformationen automatisch erzeugen zu können, wird bei jedem Aufruf der aktuelle Controller und die aktuelle Action im globalen Objekt $::request in den Methoden controller bzw. action gespeichert.
Die Methode controller enthält dabei nur den Basisnamen des Controllers, beispielsweise BackgroundJob für neuen Controller-Stil (Datei SL/Controller/BackgroundJob.pm) bzw. oe für alten Code (Datei bin/mozilla/oe.pl).
Die Action enthält ebenfalls nur den Basisnamen für neue Controller (also z.B. show, wenn im Controller action_show aufgerufen wird) bzw. den bereits rückübersetzen Namen für alte Controller (z.B. update, wenn im Rechnungs-Controller der Button mit der Beschriftung Erneuern gedrückt wurde). Falls bei einem alten Controller der Dispatch-Mechanismus genutzt wird, so enthält action bereits den Namen der letztlich aufgerufenen Funktion und nicht dispatcher.
Überschreiben von Kontextinformationen
Oftmals ist es erwünscht, dass mehrere Actions denselben Hilfetext erhalten. Typische Beispiele: die Funktionen add, edit und update sowie potenziell save, create, update. Hierfür kann eine Action den Hilfekontext manuell setzen. Das muss geschehen, bevor das Layout gerendert wird; de facto also vor dem ersten Aufruf von $::form->header.
Das Überschreiben unterscheidet sich für neue und alte Controller. Neue Controller definieren ihre Abweichungen deklarativ mit einem Aufruf analog zum Folgenden:
package SL::Controller::SomeController;
use parent qw(SL::Controller::Base);
__PACKAGE__->override_help_contexts(
new => 'edit', # Verlinkung auf aktuellen Controller
list => 'BackgroundJob/edit', # Verlinkung auf anderen Controller
);
Alte Controller müssen innerhalb ihrer Action den Kontext wie folgt setzen, damit die Hilfefunktion auf die Seite für den Controller other_controller und die Action other_action verlinkt:
$::request->help_system->context("other_controller/other_action");
Alternativ kann bei beiden Arten von Controller mit symbolischen Links im Dateisystem gearbeitet werden, die auf die gewünschten Seiten verweisen.
Deaktivieren des Hilfe-Links
Bei manchen Actions mag es gewünscht sein, den Hilfelink komplett zu verstecken. Dazu muss man den Hilfekontext mit einem leeren String überschreiben (undef funktioniert nicht):
# Im Layout wird hiermit kein Hilfe-Link angezeigt:
$::request->help_system->context("");
Speicherort für Hilfeseiten und Dateinamen
Alle Hilfeseiten werden im Verzeichnisbaum templates/webpages/help/content abgelegt. Darunter gibt es eine klar strukturierte Hierarchie:
- Die erste Ebene ist die Sprache. Hier wird das übliche Zwei-Buchstaben-Kürzel genutzt. Deutsche Hilfeseiten werden also im Unterbaum
deabgelegt. - Die zweite Ebene entspricht dem Controllernamen.
- Für jede Action existiert dann eine Datei, deren Name die Action zzgl. Endung
.mmdist.
Der vollständige Pfad für die deutsche Hilfeseite zur Seite zum Anlegen von Artikeln (Action add im Controller ic) lautet also templates/webpages/help/content/de/ic/add.mmd.
Allgemeine Hilfeseiten, die keiner Action zugeordnet sind, sind ebenfalls möglich. Deren Dateinamen müssen dabei mit einem Unterstrich beginnen, um einem potenziellen Namenskonflikt aus dem Weg zu gehen. Dabei nimmt der Namen _index.mmd eine besondere Bedeutung ein, die weiter Unten im Abschnitt über die Suchreihenfolge genauer erläutert wird.
Achtung: Das Basisverzeichnis templates/webpages/help ist nur für HTML-Vorlagen gedacht, die direkt vom Controller Help benutzt werden.
Suchreihenfolge für Hilfeseiten
Beschreibung der Reihenfolge
Der Hilfe-Controller zeigt nicht ausschließlich die zum Kontext gehörende Seite an, sondern auch allgemeinere, falls die exakt gewünschte Variante nicht gefunden wird. Die Suchreihenfolge sieht wie folgt aus (der erste Treffer gewinnt):
- im Unterbaum der Benutzersprache: der exakte Dateiname
- im Unterbaum der Benutzersprache: für den Controller die Datei
_index.mmdals Übersichtsseite des Controllers - im Unterbaum der Sprache Deutsch: der exakte Dateiname
- im Unterbaum der Sprache Deutsch: für den Controller die Datei
_index.mmdals Übersichtsseite des Controllers - im Unterbaum der Benutzersprache die Datei
_index.mmdals Startseite der kivitendo-Hilfe - im Unterbaum der Sprache Deutsch die Datei
_index.mmdals Startseite der kivitendo-Hilfe
Wird keine dieser Dateien gefunden, so wird eine Fehlermeldung ausgegeben. Da eine deutsche Hilfe-Startseite mitgeliefert wird, sollte das aber nie passieren.
Beispiel
Wenn eine Benutzerin mit englischer Oberflächensprache die Hilfe im Controller CustomerVendor bei Action edit aufruft, so werden also nacheinander die folgenden Dateien gesucht (die Ziffern entsprechen den oben genannten Nummern):
templates/webpages/content/en/CustomerVendor/edit.mmdtemplates/webpages/content/en/CustomerVendor/_index.mmdtemplates/webpages/content/de/CustomerVendor/edit.mmdtemplates/webpages/content/de/CustomerVendor/_index.mmdtemplates/webpages/content/en/_index.mmdtemplates/webpages/content/de/_index.mmd
Layout und Styling
Layoutsystem
Aktuell werden Hilfeseiten ohne das kivitendo-übliche Layout (Kopfzeile, Menüsystem) gerendert.
Styling
Das Styling kann über CSS geregelt werden. Zusätzlich zum von der BenutzerIn ausgewählten Stylesheet wird die CSS-Datei help.css eingebunden, die bereits in minimaler Version existiert.
In der Hilfe-Ausgabe selber besitzt das <body>-Element die CSS-Klasse kivitendo-help. Darüber können CSS-Regeln alle Elemente greifen.
Zu implementierende Features, zu behebende Bugs
Die folgenden Dinge müssen in Text::MultiMarkup implementiert bzw. behoben werden:
Codeblöcke mit Backticks
Codeblöcke können normalerweise auch ohne Einrückung gesetzt werden, wenn sie vorne und hinten mit je einer Zeile mit drei Backticks eingeschlossen wird. Dies wird von Text::MultiMarkdown momentan nicht unterstützt und als eingebetteter Code erkannt.
Zeilenumbrüche
Einfache Zeilenumbrüche im Fließtext (also keine Leerzeile danach) werden in der Ausgabe nicht als
gerendert, sodass gar dort gar keine Zeilenumbrüche zu sehen sind.
Auf Github existiert dafür auch ein pull request.
Hervorhebungsblöcke
Ein Block soll hervorgehoben darsgestellt werden (wie z.B. solche »Achtung!«- oder »Information«-Blöcke in Textbüchern zu Programmiersprachen), wenn sie vorhe und hinten mit zwei Gleichheitszeichen eingeschlossen werden. Das unterstützt Text::MultiMarkdown momentan gar nicht.
Tabellen und
Für Tabellen werden zwar
-Elemente ausgegeben, diese stecken allerdings direkt in