7. User-Interface

7.1. Menü

7.1.1. Einleitung

Für viele Pakete ist eine Administration unerlässlich. Sofern eine Administration vorgesehen ist, muss diese über das eisfair Setup-Menü erfolgen.

Dieses Kapitel der Entwicklerdokumentation beschreibt die Erstellung und Einbindung eigener Untermenüs in das eisfair Menüsystem.

Die einzelnen Menüs liegen unter /var/install/menu/ und sind in einer XML-ähnlichen Syntax geschrieben. Wichtig dabei ist, dass jedes Tag vollständig in einer separaten Zeile steht. Der Dateiname muss nach folgendem Schema aufgebaut sein:

setup.services.$package[.$submenu].menu

Beispiel:

/var/install/menu/setup.services.foo.menu
/var/install/menu/setup.services.foo.bar.menu

Beispiel:

setup.services.foo.menu

<!-- /var/install/menu/setup.services.foo.menu -->
<!-- Creation:     2005-04-09  max             -->
<!-- Last Update:  2005-04-09  max             -->
<title>Administration of Package Foo</title>
<package>foo</package>
<version/>
<doc>Read Foo Documentation</doc>
<edit>Edit Foo Configuration</edit>
<menu file="setup.services.foo.bar.menu">All bar functions of foo</menu>
<init task="start">Start Foo</init>
<init task="stop">Stop Foo</init>
<script file="foo-dosomething">Do Something</script>

Warnung

Da derzeit keine mehrsprachigen Menüs unterstützt werden, müssen die Menütexte in Englisch verfasst sein.

7.1.2. Verfügbare Tags

Im folgenden werden die einzelnen Tags mit den jeweiligen Optionen erklärt.

7.1.2.1. <!-- -->-Tag

Mit dem <!-- -Tag wird eine Kommentarzeile eingeleitet und mit dem --> -Tag beendet.

Beispiel:

<!-- Creation: 2005-04-09 jed -->

Warnung

Es dürfen nicht mehrere Kommentarzeilen zusammengefasst werden, dies führt im classic Menu zu einem Fehler in der Darstellung.

Beispiel: So nicht

<!--
/var/install/menu/setup.services.foo.menu
Creation:     2005-04-09  max
Last Update:  2005-04-09  max
-->

7.1.2.2. <title>-Tag

Mit dem <title>-Tag wird der Titel des Menüs angegeben.

In jedem Menü und Untermenü muss das <title>-Tag gesetzt werden.

Beispiel:

<title>Administration of Package Foo</title>

7.1.2.3. <package>-Tag

Mit dem <package>-Tag wird die Umgebungsvariable PACKAGE gesetzt. Diese kann dann von abhängigen Skripten ausgewertet werden.

In jedem Menü und Untermenü eines Pakets muss ein <package>-Tag gesetzt werden.

Beispiel:

<package>foo</package>

7.1.2.4. <version>-Tag

Mit diesem Tag wird gesteuert, dass die aktuelle eisfair-Version und eiskernel-Version auf dieser Menüebene angezeigt werden sollen.

Beispiel:

<version/>

7.1.2.5. <menu>-Tag

Zum Einhängen eines Untermenüs dient der <menu>-Tag. Hier wird mit der Option file="untermenü" die Menüdatei des Untermenüs angegeben. Diese muss ebenfalls den Spezifikationen des vorliegenden Kapitels genügen.

Der anzuzeigende Name des Untermenüs wird innerhalb des Tags angegeben.

Beispiel:

<menu file="setup.services.foo.bar.menu">All bar functions of foo</menu>

Die Menüdateien müssen alle unter /var/install/menu/ liegen und den Namen setup.services.$package.menu bzw. setup.services.$package.$submenu.menu tragen.

Tipp für fortgeschrittene Entwickler

Beim Tag <menu> kann optional die Option package="" verwendet werden um die Variable $PACKAGE explizit für ein Untermenü zu setzen. Dies entspricht der Verwendung des Tags <package> in diesem Untermenü.

Dieses Vorgehen ist nur für generische Untermenüs (z.B. ACFH) gedacht, bei denen eine explizite Verwendung des Tags <package> nicht möglich ist.

7.1.2.6. <doc>-Tag

Die Dokumentation des Paketes oder eine beliebige andere Datei im Unix-Textformat kann mit Hilfe des <doc>-Tags angezeigt werden.

Die anzuzeigende Datei wird mit der Option file="" angegeben. Sofern die Datei im Verzeichnis /usr/share/doc/$package liegt, ist die Angabe des Dateinamens ausreichend.

Wird kein Dateiname angegeben, so wird die Datei /usr/share/doc/$package/$package.txt angezeigt. Bei abweichenden Verzeichnissen muss der absolute Pfad mit angegeben werden.

Der Aufbau der Paketdokumentation ist im entprechenden Kapitel der vorliegenden Entwicklerdokumentation beschrieben.

Zur Anzeige auf der Konsole wird automatisch der in der Basiskonfiguration eingestellte PAGER verwendet.

Beispiele:

<doc file="foo.txt">Read Foo Documentation</doc>
<doc file="/usr/share/doc/foo/bar.txt">Display bar-txt</doc>

7.1.2.7. <edit>-Tag

Mit dem <edit>-Tag wird eine Funktion zum Editieren der eisfair Konfiguration eingehängt. Es wird dabei immer die mit dem <package>-Tag gesetzte Konfiguration bearbeitet.

Bei der Option package="" kann optional der Name der Konfigurationsdatei unter /var/config.d/ angegeben werden. Dieser entspricht dem Namen des Paketes.

Der im Menü anzuzeigende Text ist innerhalb des Tags anzugeben.

Auf der Konsole wird automatisch der in der Basiskonfiguration eingestellte Konfigurationseditor verwendet. Alternative Administrationsoberflächen bieten teilweise eigene Editoren.

Voraussetzung für die Verwendung des <edit>-Tags sind:

• Die Konfiguration steht in /etc/config.d/$package und entspricht den Richtlinien für eine eisfair Konfiguration.

• Es existiert eine Standardkonfiguration /etc/default.d/$package.

• Es wird die Gültigkeitsprüfung mittels /etc/check.d/$package durchgeführt.

• Es existiert ein spezifikationskonformes Apply-Skript /var/install/config.d/$package.sh zum Schreiben der „nativen“ Konfigurationsdateien des Pakets.

• /etc/init.d/$package kennt den Parameter „restart“ zum Neustarten des Pakets.

Beispiel:

<package>foo</package>
<edit>Edit Foo Configuration</edit>
<edit package="myfoo">Edit MyFoo Configuration</edit>
<edit stopstart>Stop process, edit configuration, start process</edit>

Die Verarbeitung des Parameters „restart“ in /etc/init.d/$package sieht im einfachsten Fall so aus:

Beispiel:

restart)
    $0 stop
    $0 start
    ;;

Sollte ein Neuschreiben der Konfiguration nur möglich sein, wenn das Paket vorher gestoppt wurde, dann kann dazu die Option stopstart genutzt werden. In diesem Fall wird nicht /etc/init.d/$package restart zum Neustarten des Pakets verwendet, sondern es wird als erstes das Paket mittels /etc/init.d/$package stop angehalten, bevor die Konfiguration neu geschrieben und danach das Paket wieder gestartet wird. Diese Vorgehensweise darf nur verwendet werden, wenn der normale Ablauf nicht möglich ist!

7.1.2.8. <init>-Tag

Funktionen in /etc/init.d/$package können über die standardisierte Schnittstelle <init> aufgerufen werden. Als Option wird die durchzuführende Aktion task="" übergeben.

Es wird dazu immer das Script unter /etc/init.d/ aufgerufen, das dem in <package> gesetztem Paketnamen entspricht. Optional kann aber auch mittels der Option package="" das anzusteuernde Skript angegeben werden. Bei dieser Funktion können auch mehrere Pakete mit einem einzelnen Aufruf angesteuert werden, dazu sind diese durch ein Leerzeichen (Space) getrennt anzugeben.

Im Parameter task="" wird die Funktion angegeben. Gängige Funktionen sind start, stop oder status.

Beispiel:

<init task="start">Start Foo</init>
<init task="stop">Stop Foo</init>
<init package="foo" task="stop">Kill Foo/init>
<init task="status">Show Foo Status</init>

Tipp für fortgeschrittene Entwickler

Beim <init>-Tag können mit der Option package="" auch mehrere Pakete durch Leerzeichen getrennt angegeben werden. Die jeweiligen Aktionen werden dann für alle Pakete ausgeführt:

Beispiel:

<init package="foo bar"task="start">Foo und Bar starten</init>

7.1.2.9. <script>-Tag

Der Aufruf paketeigener Skripte erfolgt über das Tag <script>. Dort wird mit der Option file="" das auszuführende Skript angegeben.

Wenn dieses Skript unter /var/install/bin/ liegt, dann reicht die Angabe des Namens (ohne absoluten Pfad). (empfohlen)

Alternativ kann auch ein Skript in einem anderen Verzeichnis aufgerufen werden. Dazu muss der absolute Pfad mit angegeben werden. Diese Methode funktioniert nicht mehr mit zukünftigen Webconf- Versionen (siehe Webconf).

Beispiel:

<script file="foo-dosomething">Do Something</script>
<script file="/usr/local/foo/doanything">Do Anything</script>

7.1.3. Menüs auf alternativen Benutzeroberflächen

Aktuell existieren mehrere alternative Benutzeroberflächen, die Menüinhalte darstellen können. Dies sind das klassische Menüsystem, die Curses-Oberfläche und das Web-Frontend „webconf“. Teilweise unterscheiden sich die Menüsysteme in ihrer Funktion und in ihrem Verhalten, weshalb eine Möglichkeit existiert, die Sichtbarkeit von Menüeinträgen einzuschränken. Zu diesem Zweck kann bei den Tags <menu>, <doc>, <script> und <init> das optionale Attribut „ui“ angegeben werden.

Gültige Werte für das Attribut sind bislang „classic“ und „cui“. Wird das Attribut nicht angegeben ist der entsprechende Menüeintrag immer sichtbar. Wird „ui“ mit dem Wert „classic“ angegeben ist der Eintrag lediglich im klassischen Menü sichtbar, während „cui“ das selbe für das Curses-Menü leistet. Es ist auch möglich mehrere Werte durch Komma getrennt anzugeben.

Beispiel:

<doc file="foo.txt">This item is always visible</doc>
<script file="foo.cui.sh" ui="cui">Curses mode only</script>
<menu file="setup.foo.menu" ui="classic">Classic mode only</menu>

7.1.4. Dynamisches Verhalten in Menüs

Falls das bis hierher beschriebene statische Verhalten von Menüs nicht ausreicht, um den Anforderungen eines Paketes zu genügen, können Skripte zur Vor- und Nachbearbeitung von Menüaktionen eingebunden werden. Damit kann z.B. dynamisch ein Untermenü oder eine Dokumentationsdatei erstellt werden.

Zu diesem Zweck kennen die Menü-Tags <menu>, <doc>, <edit>, <init> und <script> die optionalen Attribute „pre“ und „post“. Als Wert für die beiden Attribute wird dabei der Verweis auf ein Programm oder ein Shell-Skript erwartet, das entweder mit einem absoluten Pfad oder nur mit seinem Dateinamen angegeben wird. Im zweiten Fall wird angenommen, dass die Datei vom Paketentwickler im Verzeichnis /var/install/bin abgelegt wurde.

Beispiel:

<menu file="setup.foo.dyn.menu" pre="foo_menu.sh">Dynamic Menu</menu>
<doc pre="foo_compose_mod_doc.sh">View Foo Modules Doc</doc>

Im Beispiel wird das Skript /var/install/bin/foo_menu.sh aufgerufen, bevor das Untermenü geöffnet wird. Ein entsprechendes post-Skript würde entsprechend beim Verlassen des Untermenüs ausgeführt.

Hinweis

In fast allen Anwendungsfällen reicht das statische Verhalten des Menüs mit dessen Möglichkeiten vollkommen aus. Das dynamische Verhalten richtet sich in erster Linie an erfahrene Paketentwickler, welche eine Funktionalität benötigen, die in eisfair noch nicht vorgesehen ist.

An die pre/post-Skripte bzw. -Programme werden eine Reihe von Parametern übergeben, mit denen sich deren Verhalten steuern lässt. Die zu den jeweiligen Tags passenden Parameter sind in der folgenden Tabelle dargestellt:

Tag	$1	$2	$3	$4	$5	$6
<menu>	„pre“ „post“	$package	„menu“	$menu_file		$menuitem
<doc>	„pre“ „post“	$package	„doc“	$doc_file		$menuitem
<edit>	„pre“ „post“	$package	„edit“	$config_file	$stopstart	$menuitem
<init>	„pre“ „post“	$package	„init“	$init_file	$init_task	$menuitem
<script>	„pre“ „post“	$package	„script“	$shell_script		$menuitem

Der Parameter $stopstart des <edit> Tags nimmt die Werte „apply“ oder „apply-stopstart“ an, je nachdem, ob der zu konfigurierende Dienst neu gestartet werden muss oder nicht.

Dateiverweise wie $shell_script werden immer mit einem absoluten Pfad an die pre/post-Skripte übergeben. Steht im Menü die Datei ohne Pfadangabe, dann wird der Pfad nach dem in der folgenden Tabelle dargestellten Schema erweitert.

Datei	Name und absoluter Pfad
menu file	/var/install/menu/$menu_file
doc file	/usr/share/doc/$package/$doc_file
config file	/etc/config.d/$config_file
init file	/etc/init.d/$init_file
shell script	etc/init.d/$shell_script

Das Argument $menuitem teilt dem aufgerufenen Skript mit, über welchen Menüpunkt der Aufruf erfolgt ist. D.h. hier ist immer der Text des Menüeintrags enthalten, der auch dem Anwender des Menüs angezeigt wird.

Sollte ein pre/post-Skript eine Fehlerbedingung feststellen, so kann es durch einen Rückgabewert ungleich „0“ (z.B. exit 1) diesen Fehler an das Menü signalisieren. Im Falle des pre-Skripts wird dadurch zudem die Ausführung der mit dem Menü-Tag verbundenen Aktion unterbunden. Im Falle von Fehlern sollte in jedem Fall über die Standardausgabe oder die Fehlerausgabe eine erklärende Fehlermeldung erfolgen.

Beispiel:

echo "Unable to write menu file "\$3"!"
exit 1

Hinweis

Die mit einem Tag verbundene Menüaktion wird auch dann nicht ausgeführt, wenn das in der „pre“ Option angegebene Programm oder Skript nicht gefunden oder nicht ausgeführt werden konnte. Eine entsprechende Fehlermeldung wird in diesem Fall vom System erzeugt.

7.1.5. Untermenüs einhängen und entfernen

Um eigene Untermenüs ins eisfair Menü einhängen zu können, gibt es die Skripte /var/install/bin/add-menu und /var/install/bin/del-menu. Beide Skripte werden mit den selben Parametern aufgerufen, deshalb werden diese nur einmal gemeinsam erklärt.

/var/install/bin/add-menu MENUE UNTERMENUE MENUETEXT
/var/install/bin/del-menu MENUE UNTERMENUE

siehe auch:

/var/install/bin/add-menu

/var/install/bin/del-menu

MENUE gibt das Menü an, unter welches das neue Menü gehängt werden soll. UNTERMENUE gibt das Untermenü an, dass in MENUE eingehängt werden soll. MENUETEXT gibt den in MENUE anzuzeigenden Text an.

Beispiele:

/var/install/bin/add-menu         \
    setup.services.menu           \
    setup.services.foo.menu       \
    "Foo Configuration"

/var/install/bin/del-menu         \
    setup.services.menu           \
    setup.services.foo.menu

Warnung

Hier hat sich die Aufrufsyntax gegenüber der alten Version geändert. Der alte Aufruf mit dem auszuführenden Skript als Parameter funktioniert aus Kompatibilitätsgründen weiter, darf aber bei neuen Releases nicht mehr verwendet werden!

Hinweis

Bis inklusive Base Version 1.0.7 wurde eine andere Syntax für die Menüstruktur verwendet. Dabei konnten aus dem Menü nur Shellscripts aufgerufen werden, die ggf. wieder ein Menü anzeigten.

Diese Menüsyntax ist veraltet und wird nur übergangsweise parallel unterstützt. Alternative Administrationsoberflächen werden mit der alten Menüstruktur nicht funktionieren, weshalb die Verwendung der alten Struktur in neuen Releases nicht mehr zulässig ist.

Bei Verwendung der neuen Menüsyntax sind die alten Scripte wie foo- edit, foo-doc oder foo-bar nicht mehr nötig, da viele Funktionen jetzt standardisiert aufgerufen werden.

Sollte es aus einem Grund einmal nötig sein eine komplett neue Menüdatei anzulegen, so kann dies durch Aufruf des Skriptes /var/install/bin/create-menu erledigt werden.

/var/install/bin/create-menu MENUE MENUETITEL

siehe auch:

/var/install/bin/create-menu

MENUE gibt das Menü an, welches erzeugt werden soll. MENUETITEL gibt den Menütitel an, welcher über dem Menü angezeigt werden soll.

7.2. Dokumentation

7.2.1. Dokumentation

Die eigentliche Dokumentation eines Pakets muss im Verzeichnis /usr/share/doc/$package abgelegt werden und eine im Unix-Textformat erstellte Datei Namens $package.txt sein.

In der Dokumentation müssen zumindest folgende Punkte genauer erklärt werden:

• Welche weiteren Pakete werden benötigt?

• Eventuelle Konfigurationsdateien und die in ihr definierten Variablen.

• Die Punkte im Setup-Menü, soweit sie dieses Paket betreffen.

• Die Funktionen des Pakets.

• Wie arbeitet dieses Paket mit anderen Paketen zusammen?

Zusätzliche Dokumentation, die den Originalquellen normalerweise beiliegt (man-Pages, info-Dateien, README, etc.), dürfen nicht mitgeliefert werden.

7.2.2. Changelog

Im Verzeichnis /usr/share/doc/$package ist eine Datei changes.txt anzulegen, in dem die Veränderungen, die von Version zu Version am Paket durchgeführt werden, kurz beschrieben werden. Bewährt hat sich eine Form wie in folgendem Beipiel.

Beispiel für ein Changelog:

1.0.6
-----
- added file /bin/bigone
- deleted obsolete variable ONE in
  /etc/config.d/master
- renamed /etc/old to /etc/new
-
-

1.0.5
-----
- modified some comments in /etc/this
-
-

Dabei sollten die letzten änderungen jeweils oben in der Datei changes.txt stehen. Uralte änderungen können mit der Zeit auch entfallen.