Damit die Oberfläche möglichst einheitlich aussieht, werden die Formulare über sogenannte Formulardateien erzeugt, in denen der formale Aufbau beschrieben ist. Im Paket ist ein Pseudodienst namens `webcnfex' enthalten, anhand dessen man sich anschauen kann, wie das Ganze dann im Browser aussieht.
Es sollte zur Zeit bereits möglich sein, die komplette Administration eines
Dienstes über den Browser durchzuführen![[*]](footnote.png)
.
Die Funktionen `Package administration' und `User administration' aus dem
Setup sind noch nicht im Paket integriert.
Beim Klick auf den Punkt `Service administration' werden alle Dateien aus /var/install/form
gelesen, die auf `.main' enden. Das sind die sogenannten Menüdateien, die den Ausgangspunkt
darstellen und aus denen die Liste der Links erstellt wird, die dann zur konkreten Konfiguration
führen.
In der Menüdatei wird festgelegt, wie das Konfigurationsformular und die Dokumentation des
Paketes heißen, sowie welche Funktionen zur Administration bereitstehen und welche Formulardatei
für welche Funktion zuständig ist. In unserem Beispiel benötigen wir also erstmal die Datei
/var/install/form/webcnfex.main.
<menuname>Servicename</menuname> <doc name="Menüpunktname" file="Dokumentation"/> <config form="Formular"/> <option name="Optionsname" form="Formular"/> <empty/> ... <option .../>
.
.
Die Reihenfolge der Tags ist relevant und sollte immer wie oben angegeben lauten, damit eine einheitliche Menüführung gewährleistet wird. Der Tag <menuname ...> ist zwingend, alle anderen sind optional und können entfallen.
Kommentare sind möglich und werden mit `#' eingeleitet. Alles ab diesem Zeichen wird, genauso wie Leerzeilen, ignoriert, es sei denn es steht innerhalb eines Tags.
<menuname>Webconf Service example</menuname> <doc file="/usr/share/doc/webconf/webcnfex.txt"/> <doc name="Alternative Doc" file="/usr/share/doc/webconf/webcnfex-alt.txt"/> <empty/> <config form="webcnfex"/> <empty/> <option name="Part One" form="webcnfex.one"/> <option name="Part Two" form="webcnfex.two"/> <option name="Part Three" form="webcnfex.three"/> <option name="Part Four" form="webcnfex.four"/>
In der Menüdatei wird im Tag <config ...> angegeben, wie das Konfigurationsformular heißt, das
zum Anpassen der Konfiguration zuständig ist (siehe Die Menüdatei).
Dabei ist zu beachten, daß diese Datei genauso heißen muß, wie die Konfigurationsdatei,
die sich in /etc/config.d befinden muß. Desweiteren wird nach einer Hilfedatei
(Syntax Hilfedatei) gesucht, die ebenfalls genauso heißen und sich in
/var/install/help befinden muß. Wenn diese Hilfedatei gefunden wird, dann wird zu jeder Variablen
ein Hilfepunkt angelegt.
Nach dem Absenden des Formulars werden die Variablen in der Konfigurationsdatei gespeichert.
Falls der Benutzer `Apply' gewählt hat, wird versucht das zugehörige Skript aus
/var/install/config.d aufzurufen, welches wiederum den gleichen Namen haben muß wie das Konfigurationsformular. Falls `Reload' gewählt wurde, dann
wird das Formular mit den neuen Inhalten neu erzeugt.
<group name="Gruppenname">
<option name="Optionsname" type="Optionstyp" master="Master-Option" ro="yes|no">
<val>Select-Value</val>
<match>Match-Pattern</match>
<errormsg>Eigene Fehlermeldung, falls Match-Pattern nicht zutrifft.</errormsg>
<file>Konfigurationsdatei</file>
<ref>Referenzvariable</ref>
</option>
...
<option ...>
...
</option>
</group>
...
<group ...>
...
</group>
gedacht. Wenn man z.B. in seinem
Paket auf die verschiedenen eingestellten Netzwerkkartentreiber zugreifen will,
dann kann man die Variablen ETH_DRV_x dazu verwenden. Damit der Benutzer nur
Werte für x angibt, die auch eingestellt sind, kann man den Typ `REF' dazu
verwenden. Mit <file ...>' wird die Konfigurationsdatei angeben, in der
die Variablen stehen und mit <ref ...> gibt man die Master-Variable an,
in diesem Beispiel wäre das ETH_DRV_N. Damit wird eine Auswahlbox erzeugt, die
nur Werte von 1 bis Wert der Master-Variablen enthält. Der Benutzer kann auch
mehrere Einträge auswählen, diese werden mit Leerzeichen getrennt in die
Konfigurationsvariable geschrieben.
Falls die Tags <val> und <match> für eine Option nicht benötigt werden,
dann kann auch der </option>-Tag entfallen und statt dessen wird der öffnende
<option ...>-Tag am Ende mit `/' geschlossen (z. B.
<option name=``foobar''
type=``YESNO''/>).
Weiterhin gibt es noch einen <empty/>-Tag, welcher bewirkt, daß eine Leerzeile an der Stelle im Formular erzeugt wird, an der sich dieser Tag im Konfigurationsformular befindet.
Die Reihenfolge der Optionen in den Tags und die Reihenfolge von <val> und <match> ist egal. Leere Zeilen und Kommentare sind erlaubt und werden ignoriert. Ein Kommentar wird eingeleitet durch `#' (außer `#' steht innerhalb eines Tags, dann gilt es nicht als Kommentar) und reicht bis zum Zeilenende.
Beispiel ist das mitgelieferte Konfigurationsformular von webcnfex:
<group name="General settings">
<option name="WEBCNFEX_START" type="YESNO"/>
<option name="WEBCNFEX_COMMENT" type="LINE"/>
<option name="WEBCNFEX_TYPE" type="SELECT">
<val>auto</val>
<val>user</val>
<val>random</val>
</option>
<option name="WEBCNFEX_LIMIT" type="LINE">
<match>#dec_10_s#</match>
</option>
<option name="WEBCNFEX_REF" type="REF">
<file>base</file>
<ref>ETH_DRV_N</ref>
</option>
</group>
<empty/>
<group name="Aliases">
<option name="WEBCNFEX_ALIAS_N" type="LINE">
<match>#dec_0_s#</match>
</option>
<option name="WEBCNFEX_ALIAS_#" type="LINE" master="WEBCNFEX_ALIAS_N"/>
</group>
<empty/>
<group name="Lists">
<option name="WEBCNFEX_LIST_N" type="LINE">
<match>#dec_0_s#</match>
</option>
<option name="WEBCNFEX_LIST_#_NAME" type="LINE" master="WEBCNFEX_LIST_N">
<match>#domain_s#</match>
</option>
<option name="WEBCNFEX_LIST_#_USER_N" type="LINE" master="WEBCNFEX_LIST_N">
<match>#dec_0_s#</match>
</option>
<option name="WEBCNFEX_LIST_#_USER_##_SURNAME" type="LINE" master="WEBCNFEX_LIST_#_USER_N"/>
<option name="WEBCNFEX_LIST_#_USER_##_LASTNAME" type="LINE" master="WEBCNFEX_LIST_#_USER_N"/>
<option name="WEBCNFEX_LIST_#_USER_##_TRAFFIC" type="SELECT" master="WEBCNFEX_LIST_#_USER_N">
<val>low</val>
<val>middle</val>
<val>high</val>
</option>
<option name="WEBCNFEX_LIST_#_ADMIN" type="LINE" master="WEBCNFEX_LIST_N">
<match>#email_s#</match>
</option>
<option name="WEBCNFEX_LIST_#_ERRORS" type="LINE" master="WEBCNFEX_LIST_N">
<match>#email_s#</match>
</option>
<empty/>
<option name="WEBCNFEX_LIST_GOD" type="LINE">
<match>#email_s#</match>
</option>
</group>
<empty/>
<group name="Accounts">
<option name="WEBCNFEX_ACCOUNT_N" type="LINE">
<match>#dec_0_s#</match>
</option>
<option name="WEBCNFEX_ACCOUNT_#_NAME" type="LINE" master="WEBCNFEX_ACCOUNT_N"/>
<option name="WEBCNFEX_ACCOUNT_#_PASS" type="LINE" master="WEBCNFEX_ACCOUNT_N"/>
<option name="WEBCNFEX_ACCOUNT_#_HOME" type="LINE" master="WEBCNFEX_ACCOUNT_N">
<match>#dir_s#</match>
</option>
<option name="WEBCNFEX_ACCOUNT_#_GROUP" type="LINE" master="WEBCNFEX_ACCOUNT_N">
<match>#group_s#</match>
</option>
<option name="WEBCNFEX_ACCOUNT_#_TRUSTED" type="YESNO" master="WEBCNFEX_ACCOUNT_N"/>
</group>
In der Menüdatei wird im Tag <option ...> für jede Servicefunktion angegeben, wie das Serviceformular heißt, das für die jeweilige Funktion zuständig ist (siehe Die Menüdatei). Dabei ist zu beachten, daß diese Dateien relativ zu /var/install/form gesucht werden.
<form name="Servicename" prep="Skript" help="Helpfile">
<subform name="Subformname" button="Buttonname" script="Skript" target="Target">
<option name="Optionsname" vname="Variablenname" hname="Helpoption" type="Typ">
<match>Match-Pattern</match>
<size>Size</size>
<align>LEFT|RIGHT|CENTER|BLOCK</align>
<source>Sourcefile</source>
<sourcerange>Range</sourcerange>
<item>Item</item>
<text>
Text
</text>
</option>
...
<option ...>
...
</option>
</subform>
...
<subform ...>
...
</subform>
</form>
Die Reihenfolge der Optionen im Tag ist egal.
.
Die Reihenfolge der Optionen im Tag ist egal.
<subform ...>). Ist optional und kann entfallen, dann wird
`Optionsname' als Bezeichner verwendet.
wird einfacher Text ausgegeben,
bei `FIELD' wird ein mehrzeiliges Eingabefeld erzeugt, bei `LINE' ein einzeiliges.
`SELECT' bewirkt eine Auswahlbox mit Einfachauswahl und `SELECT_M' eine mit Mehrfachauswahl. `CHECKBOX' erzeugt ein oder mehrere Checkboxen
und `CHOICE' ein oder mehrere Radiobuttons.
Die Reihenfolge der Optionen im Tag ist egal.
. Falls `r1' == 0, dann wird die ganze Datei als Vorbelegung gewählt;
falls `r2' = `x', dann wird die Datei von `r1' bis Dateiende als Vorbelegung gewählt. Falls
type=``LINE'' dann wird eine Zahl erwartet, die die Zeilennummer angibt, in der der Text steht,
der als Vorbelegung gewählt werden soll. Steht dort 0 oder entfällt der Tag, dann wird die erste
Zeile genommen, falls <source> existiert.
Es gibt noch einen <empty/>-Tag, der eine Leerzeile im Formular erzeugt. Für Kommentare und Leerzeilen im Formfile gilt das Gleiche, wie beim Konfigurationsformular.
Die Tags innerhalb <option> dürfen in beliebiger Reihenfolge stehen.
Beispiel 1 (webcnfex.one):
<form help="webcnfex" name="webconfex one">
<subform name="subform one of part one" button="here we go" script="dump.sh" target="FRAME">
<option type="TEXT">
<text>
This is only a little text. Nothing interesting in. Don't know what
to say.<br>
This is only a little text. Nothing interesting in. Don't
know what to say. This is only a little text. Nothing interesting
in. Don't know what to say.<br>
(It's boring, isn't it?).<br>
This is only a little text.<br>
Nothing interesting in.<br>
Don't know what to say.<br>
This is only a little text. Nothing interesting in. Don't know what
to say. Yeah, really boring.
</text>
<align>left</align>
</option>
<option type="TEXT">
<text>
This is only a little text. Nothing interesting in. Don't know what
to say. This is only a little text. Nothing interesting in. Don't
know what to say. This is only a little text. Nothing interesting
in. Don't know what to say. (It's boring, isn't it?). This is only
a little text. Nothing interesting in. Don't know what to say. This
is only a little text. Nothing interesting in. Don't know what to
say. Yeah, really boring.
</text>
<align>BLOCK</align>
</option>
<empty/>
<empty/>
<option name="multi-select" vname="msel" type="SELECT_M" hname="help1">
<size>4</size>
<item>this</item>
<item>is a</item>
<item>multi</item>
<item>select</item>
<item>box</item>
</option>
<option name="single-select" vname="ssel" type="SELECT" hname="help2">
<size>1</size>
<item>you</item>
<item>can</item>
<item>choose</item>
<item>only</item>
<item>one</item>
</option>
<empty/>
<empty/>
<option type="TEXT">
<text>
This is only a little text. Nothing interesting in. Don't know what
to say.<br>
This is only a little text. Nothing interesting in. Don't
know what to say. This is only a little text. Nothing interesting
in. Don't know what to say.<br>
(It's boring, isn't it?).<br>
This is only a little text.<br>
Nothing interesting in.<br>
Don't know what to say.<br>
This is only a little text. Nothing interesting in. Don't know what
to say. Yeah, really boring.
</text>
<align>RIGHT</align>
</option>
<option type="TEXT">
<text>
This is only a little text. Nothing interesting in. Don't know what
to say.<br>
This is only a little text. Nothing interesting in. Don't
know what to say. This is only a little text. Nothing interesting
in. Don't know what to say.<br>
(It's boring, isn't it?).<br>
This is only a little text.<br>
Nothing interesting in.<br>
Don't know what to say.<br>
This is only a little text. Nothing interesting in. Don't know what
to say. Yeah, really boring.
</text>
<align>CENTER</align>
</option>
</subform>
</form>
Beispiel 2 (webcnfex.two):
<form help="webcnfex" prep="webcnfex.two.prep" name="webconfex two">
<subform name="subform one of part two" button="click me" script="dump.sh" target="NEW">
<option type="TEXT">
<text>
input-line with regex-check
</text>
</option>
<option name="type sth." vname="ts1" type="LINE" hname="help3">
<size>30</size>
<source>/tmp/webcnfex.two.source1</source>
<match>#ip_s#</match>
</option>
<option name="type sth." vname="ts2" type="LINE" hname="help4">
<size>30</size>
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>1</sourcerange>
<match>#dir_s#</match>
</option>
</subform>
<empty/>
<empty/>
<empty/>
<subform name="subform two of part two" script="dump.sh" target="FRAME">
<option name="checkboxes t1" vname="cbt1" type="CHECKBOX" hname="help5">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>2-5</sourcerange>
<size>v</size>
</option>
<empty/>
<option name="checkboxes t2" vname="cbt2" type="CHECKBOX" hname="help6">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>2-5</sourcerange>
<size>h</size>
</option>
<option name="checkboxes t3" vname="cbt3" type="CHECKBOX" hname="help7">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>2-5</sourcerange>
<size>h3</size>
</option>
<option name="checkboxes t4" vname="cbt4" type="CHECKBOX" hname="help8">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>2-5</sourcerange>
<size>v3</size>
</option>
</subform>
<empty/>
<empty/>
<empty/>
<subform name="subform three of part two" script="dump.sh" target="FRAME">
<option name="buttons t1" vname="ct1" type="CHOICE" hname="help9">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>6-10</sourcerange>
<size>v</size>
</option>
<empty/>
<option name="buttons t2" vname="ct2" type="CHOICE" hname="help10">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>6-10</sourcerange>
<size>h</size>
</option>
<option name="buttons t3" vname="ct3" type="CHOICE" hname="help11">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>6-10</sourcerange>
<size>h3</size>
</option>
<option name="buttons t4" vname="ct4" type="CHOICE" hname="help12">
<source>/tmp/webcnfex.two.source1</source>
<sourcerange>6-10</sourcerange>
<size>v3</size>
</option>
</subform>
</form>
Wie weiter oben schon angedeutet, ist es möglich Hilfepunkte in die Formulare zu integrieren,
um dem Benutzer zusätzliche Unterstützung zu geben. Dies geschieht mit der Hilfedatei.
Desweiteren können die Formulare per CSS gestaltet werden.
Die Hilfedateien müssen sich in /var/install/help befinden. Im Falle der der Hilfedatei zur Konfiguration muß diese genauso heißen wie das Konfigurationsformular (siehe oben: Das Konfigurationsformular). Im Falle der Hilfedatei zur Serviceadministration kann der Name frei festgelegt werden (siehe oben: Das Serviceformular). Weiterhin kann jede Servicefunktion eine eigene Hilfedatei haben, man kann aber auch die gesamte Hilfe in einer einzigen Datei zusammen mit der Hilfe für die Konfiguration unterbringen. Die letzte Variante ist sicher zu bevorzugen.
<help name="Optionsname"> Hilfetext </help ...> ... <help> ... </help>
Für jeden Hilfepunkt muß ein <help ...>-Tag existieren. Dabei wird der Hilfetext der
richtigen Variablen über `Optionsname' zugeordnet, d.h. `Optionsname' muß
gleich dem Optionsnamen (im Falle des Konfigurationsformulars) bzw. gleich dem
Variablennamen (im Falle des Serviceformulars) sein, der auch in der entsprechenden
Formulardatei angegeben wurde, zu der der Hilfetext gehören soll.
Desweiteren werden in `Hilfetext' folgende Ersetzungen vorgenommen:
'\<'
'<'
'\>'
'>'
'\&'
'&'
'\"'
'"'
'\n'
'<br>'
' '
' '
'ä'
'ä'
'ö'
'ö'
'ü'
'ü'
'Ä'
'Ä'
'Ö'
'Ö'
'Ü'
'Ü'
'ß'
'ß'
"' so direkt ausgegeben werden sollen,
dann müssen sie also vorher mit `
\' maskiert werden, sonst kann es zu Fehlern bei
der Darstellung kommen. Da die Hilfe eine Webseite ist, können auch HTML-Tags in der Hilfe
verwendet werden. Leere Zeilen in der Hilfedatei sind erlaubt und werden ignoriert. Wichtig ist,
daß die Tags alleine in einer Zeile stehen. Bsp.:
<help name="Optionsname"> Ich bin ein kleiner </help> Hilfetext.
falsch
<help name="Optionsname"> Ich bin ein kleiner Hilfetext. </help>
richtig
Als Beispiel dient ein Teil der mitgelieferten webcnfex-Hilfedatei:
<help name="WEBCNFEX_START"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_COMMENT"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_TYPE"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_LIMIT"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_ALIAS_N"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_ALIAS_#"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_LIST_N"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_LIST_#_NAME"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_LIST_#_USER_N"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_LIST_#_USER_##_SURNAME"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_LIST_#_USER_##_LASTNAME"> Too lazy to put sth. ingenious here. </help> <help name="WEBCNFEX_LIST_#_USER_##_TRAFFIC"> Too lazy to put sth. ingenious here. </help> <help name="help1"> this is help. </help> <help name="help2"> help? </help>
Zur Gestaltung der Formulare wird CSS verwendet. Dabei kann man den verschiedenen HTML-Elementen Klassen zuordnen. Damit bei Bedarf jede Hauptseite anders gestaltet werden kann, habe ich den verwendeten Elementen dafür jeweils eine eigene Klasse zugewiesen. Folgende Klassen wurden verwendet:
Für die einzelnen Klassen können jeweils folgende HTML-Elemente definiert werden:
Das Stylesheet muß sich unter /usr/local/webconf/CSS befinden. Es kann entweder eine einzelne Datei sein (z.B. `foobar.css') oder ein Verzeichnis. Das Verzeichnis muß genauso heißen wie die Datei, nur ohne `.css' (z.B. /usr/local/webconf/CSS/foobar/). In diesem Verzeichnis befindet sich dann das eigentliche Stylesheet `foobar.css' und die weiteren Dateien (z.B. Bilder). Der Name des Stylesheets, der dann in der Konfigurationsdatei von Webconf angegeben wird ist dann `foobar'.
Eine gute Einführung in HTML und CSS bietet u.a. http://selfaktuell.teamone.de/
h1.index { text-align:center; }
ol.index { margin-left:40%; }
h1.error { text-align:center;
color:#FF0000; }
p.error { text-align:justify;
margin-left:5%; }
h1.chooseserv { text-align:center; }
ol.chooseserv { margin-left:40%; }
h1.chooseopt { text-align:center; }
ol.chooseopt { margin-left:40%; }
h1.confform { text-align:center; }
input.button-confform { text-align:left; }
input.text-confform { font-family:Courier, monospace;
font-weight:bold; }
textarea.confform { font-family:Courier, monospace;
font-weight:bold; }
select.confform { font-family:Courier, monospace;
font-weight:bold; }
td.optname-confform { text-align:right;
vertical-align:top;
margin-left:10px;
font-family:'lucidabright', 'Lucida Console', monospace; }
legend.confform { font-weight:bold; }
table.confform { margin:10px; }
h1.servform { text-align:center; }
legend.servform { font-weight:bold; }
input.button-servform { text-align:left; }
input.text-servform { font-family:Courier, monospace;
font-weight:bold; }
textarea.servform { font-family:Courier, monospace;
font-weight:bold; }
select.servform { font-family:Courier, monospace;
font-weight:bold; }
td.optname-servform { text-align:right;
vertical-align:top;
margin-left:10px;
font-family:'lucidabright', 'Lucida Console', monospace }
p.servform { font-family:Verdana, Lucida, Courier, monospace;
margin-left:10px;
margin-right:10px;
margin-top:10px;
margin-bottom:10px; }
table.servform { margin:10px; }
Es gibt folgende vordefinierte reguläre Ausdrücke:
oder `#ip#' steht.
.
.
.
.
. Dabei steht `localpart'
für eine Zeichenkette bestehend aus den ASCII-Zeichen
\32d-
\126d außer '
\',
`:', `,', `;', `@', `(', `)', `[', `]', '' oder für einen in '' eingfaßten String, in dem entweder alle ASCII-Zeichen
\0d-
\127d mit `
\' maskiert vorkommen dürfen, oder alle ASCII-Zeichen
\0d-
\127d außer `
\10d', `
\13d', '', `
\'.
.
`name' steht dabei für eine Zeichenkette, die mit einem Zeichen aus [a-z] anfangen, mit einem Zeichen
aus [a-z0-9] enden muß und ansonsten Zeichen aus [a-z0-9+_-] enthalten darf.
Die vordefinierten Pattern können beliebig mit normalen regulären Ausdrücken kombiniert werden und es kann jeder noch mit einem Suffix versehen werden (innerhalb von `#...#'). Das Suffix `_e' (empty) bewirkt, daß der Inhalt auch leer sein darf, `_s' (strict) erzwingt einen Match auf die ganze Zeile und `_se' bzw. `_es' kombiniert beides.
Die Funktionsweise von regulären Ausdrücken unter Perl kann man auf http://www.perldoc.comunter dem Kapitel `perlre' nachlesen. Falls das komplette Perlpaket auf dem eigenen System installiert ist, kann man diese Dokumentation auch mit dem Aufruf `perldoc perlre' aufrufen. Man beachte, daß `perldoc' in dem Perlpaket für eisfair nicht enthalten ist.