Unterabschnitte

User-Interface

Menue

Einleitung

Fuer viele Pakete ist eine Administration unerlaesslich. Sofern eine Administration vorgesehen ist, muss diese ueber das eisfair Setup-Menue erfolgen.

Dieses Kapitel der Entwicklerdokumentation beschreibt die Erstellung und Einbindung eigener Untermenues in das eisfair Menuesystem.

Die einzelnen Menues liegen unter /var/install/menu/ und sind in einer XML-aehnlichen Syntax geschrieben. Wichtig dabei ist, dass jedes Tag vollstaendig in einer separaten Zeile steht. Der Dateiname muss nach folgendem Schema aufgebaut sein:

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

Beispiele:

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

ACHTUNG
Da derzeit keine mehrsprachigen Menues unterstuetzt werden, muessen die Menuetexte in Englisch verfasst sein.


Verfuegbare Tags

Im folgenden werden die einzelnen Tags mit den jeweiligen Optionen erklaert.

<!-- - >-Tag

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

Beispiel:

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

ACHTUNG
Es duerfen nicht mehrere Kommentarzeilen zusammengefasst werden, dies fuehrt 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
-->

<title>-Tag

Mit dem <title>-Tag wird der Titel des Menues angegeben.

In jedem Menue und Untermenue muss das <title>-Tag gesetzt werden.

Beispiel:

<title>Administration of Package Foo</title>

<package>-Tag

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

In jedem Menue und Untermenue eines Pakets muss ein <package>-Tag gesetzt werden.

Beispiel:

<package>foo</package>

<version>-Tag

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

Beispiel:

<version/>

<url>-Tag

Dient zur Anzeige der aktuellen Paket-Installationsquelle.

Beispiel:

<url/>

<menu>-Tag

Zum Einhaengen eines Untermenues dient der <menu>-Tag. Hier wird mit der Option file="untermenue" die Menuedatei des Untermenues angegeben. Diese muss ebenfalls den Spezifikationen des vorliegenden Kapitels genuegen.

Der anzuzeigende Name des Untermenues wird innerhalb des Tags angegeben.

Beispiel:

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

Die Menuedateien muessen 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 fuer ein Untermenue zu setzen. Dies entspricht der Verwendung des Tags <package> in diesem Untermenue.

Dieses Vorgehen ist nur fuer generische Untermenues (z.B. ACFH) gedacht, bei denen eine explizite Verwendung des Tags
<package> nicht moeglich ist.


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

<edit>-Tag

Mit dem <edit>-Tag wird eine Funktion zum Editieren der eisfair Konfiguration eingehaengt. 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 Menue anzuzeigende Text ist innerhalb des Tags anzugeben.

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

Voraussetzung fuer die Verwendung des <edit>-Tags sind:

Beispiele:

<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 moeglich 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 moeglich ist!

<init>-Tag

Funktionen in /etc/init.d/$package koennen ueber die standardisierte Schnittstelle <init> aufgerufen werden. Als Option wird die durchzufuehrende Aktion task="" uebergeben.

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 koennen auch mehrere Pakete mit einem einzelnen Aufruf angesteuert werden, dazu sind diese durch ein Leerzeichen (Space) getrennt anzugeben.

Im Parameter task="" wird die Funktion sowie optional Aufrufparameter angegeben. Gaengige Funktionen sind start, stop oder status. Ein Parameter wird durch ein Leerzeichen getrennt in task="" mit angegeben.

Beispiele:

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

Tipp für fortgeschrittene Entwickler
Beim
<init>-Tag koennen mit der Option package="" auch mehrere Pakete durch Leerzeichen getrennt angegeben werden. Die jeweiligen Aktionen werden dann fuer alle Pakete ausgefuehrt:

Beispiel:

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


<script>-Tag

Der Aufruf paketeigener Skripte erfolgt ueber das Tag <script>. Dort wird mit der Option file="" das auszufuehrende 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 zukuenftigen Webconf-Versionen (siehe Webconf).

Beispiele:

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

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.

Beispiele:

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

Dynamisches Verhalten in Menues

Falls das bis hierher beschriebene statische Verhalten von Menues nicht ausreicht, um den Anforderungen eines Paketes zu genuegen, koennen Skripte zur Vor- und Nachbearbeitung von Menueaktionen eingebunden werden. Damit kann z.B. dynamisch ein Untermenue oder eine Dokumentationsdatei erstellt werden.

Zu diesem Zweck kennen die Menue-Tags <menu>, <doc>, <edit>, <init> und <script> die optionalen Attribute ''pre'' und ''post''. Als Wert fuer 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.

Beispiele:

<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 Untermenue geoeffnet wird. Ein entsprechendes post-Skript wuerde entsprechend beim Verlassen des Untermenues ausgefuehrt.

Hinweis
In fast allen Anwendungsfaellen reicht das statische Verhalten des Menues mit dessen Moeglichkeiten vollkommen aus. Das dynamische Verhalten richtet sich in erster Linie an erfahrene Paketentwickler, welche eine Funktionalitaet benoetigen, die in eisfair noch nicht vorgesehen ist.


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

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

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 uebergeben. Steht im Menue 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
   

Sollte ein pre/post-Skript eine Fehlerbedingung feststellen, so kann es durch einen Rueckgabewert ungleich ''0'' (z.B. exit 1 ) diesen Fehler an das Menue signalisieren. Im Falle des pre-Skripts wird dadurch zudem die Ausfuehrung der mit dem Menue-Tag verbundenen Aktion unterbunden. Im Falle von Fehlern sollte in jedem Fall ueber die Standardausgabe oder die Fehlerausgabe eine erklaerende Fehlermeldung erfolgen.

Beispiel:

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

Hinweis
Die mit einem Tag verbundene Menueaktion wird auch dann nicht ausgefuehrt, wenn das in der ''pre'' Option angegebene Programm oder Skript nicht gefunden oder nicht ausgefuehrt werden konnte. Eine entsprechende Fehlermeldung wird in diesem Fall vom System erzeugt.


Untermenues einhaengen und entfernen

Um eigene Untermenues ins eisfair Menue einhaengen zu koennen, 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 erklaert.

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

MENUE gibt das Menue an, unter welches das neue Menue gehaengt werden soll.
UNTERMENUE gibt das Untermenue an, dass in MENUE eingehaengt 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

ACHTUNG
Hier hat sich die Aufrufsyntax gegenueber der alten Version geaendert. Der alte Aufruf mit dem auszufuehrenden Skript als Parameter funktioniert aus Kompatibilitaetsgruenden weiter, darf aber bei neuen Releases nicht mehr verwendet werden!


Hinweis
Bis inklusive Base Version 1.0.7 wurde eine andere Syntax fuer die Menuestruktur verwendet. Dabei konnten aus dem Menue nur Shellscripts aufgerufen werden, die ggf. wieder ein Menue anzeigten.

Diese Menuesyntax ist veraltet und wird nur uebergangsweise parallel unterstuetzt. Alternative Administrationsoberflaechen werden mit der alten Menuestruktur nicht funktionieren, weshalb die Verwendung der alten Struktur in neuen Releases nicht mehr zulaessig ist.

Bei Verwendung der neuen Menuesyntax sind die alten Scripte wie foo-edit, foo-doc oder foo-bar nicht mehr noetig, da viele Funktionen jetzt standardisiert aufgerufen werden.

Sollte es aus einem Grund einmal noetig sein eine komplett neue Menuedatei anzulegen, so kann dies durch Aufruf des Skriptes /var/install/bin/create-menu erledigt werden.

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

MENUE gibt das Menue an, welches erzeugt werden soll.
MENUETITEL gibt den Menuetitel an, welcher ueber dem Menue angezeigt werden soll.

Dokumentation

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 muessen zumindest folgende Punkte genauer erklaert werden:

Zusaetzliche Dokumentation, die den Originalquellen normalerweise beiliegt (man-Pages, info-Dateien, README, etc.), duerfen nicht mitgeliefert werden.

Changelog

Im Verzeichnis /usr/share/doc/$package ist eine Datei changes.txt anzulegen, in dem die Veraenderungen, die von Version zu Version am Paket durchgefuehrt werden, kurz beschrieben werden.

Bewaehrt hat sich eine Form wie in folgendem Beispiel:

Beispiel fuer 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 aenderungen jeweils oben in der Datei changes.txt stehen. Uralte aenderungen koennen mit der Zeit auch entfallen.

Yves Schumann 2012-02-05