Dokumentation des Python-Moduls common.py
-----------------------------------------

(C) netEstate GmbH, www.netestate.de

1.	Installation

-Kopieren Sie common.py in das Extensions-Verzeichnis von Zope

-Erstellen Sie - am besten im Wurzelverzeichnis von Zope - folgende externen
 Methoden an, die auf gleichnamige Funktionen im Modul common zeigen:
 CgiEscape, QuotePlus, PKDateiname, GeheZuObjekt, HoleObjekt, HoleZufallszahl,
 VolleUrl, Base, SpeichereFormularDaten, Formularwert, GmTime, LocalTime, LocalTime1,
 MkTime, Time, StrfTime, StrpTime, Update_Data, UrlRead, Md5HexDigest, B64Encode,
 B64Decode, Sleep

-Legen Sie eine Property des Startverzeichnisses "ServerName" mit dem 
 Servernamen an.

-Legen Sie ein Verzeichnis /SSL im Root Folder an.

-Legen Sie eine Property SSLAktiviert von /SSL des Typs boolean an.

2.	Funktionen

Das Modul common.py stellt nützliche Hilfsfunktionen bereit, die sowohl 
in anderen Modulen als auch als externe Methoden von Zope verwendet 
werden können.

-Sleep(t) / GmTime(t) / LocalTime(t) / LocalTime1(t) / MkTime(t) / Time() /
 StrpTime(s,f) / StrfTime(f,t)
 Ruft die gleichnamigen Funktionen des Python-Moduls time auf, auf die Zope
 normalerweise keinen Zugriff bietet.

-Update_Data(file,data,ctype)
 Ruft file.update_data(data,content_type=ctype) auf.

-UrlRead(url, data = None):
 Ruft urllib.urlopen(url, data) auf.

-Md5HexDigest(data):
 Ruft md5.new(data).hexdigest() auf.

-B64Encode(data), B64Decode(data):
 Ruft die gleichnamigen Funktionen das Moduls base64 auf.

-CgiEscape(String)

Ruft cgi.escape(string,1) auf, um HTML-Sonderzeichen zu escapen - z.B. für 
die Verwendung innerhalb eines HTML-Tags. Zope bietet derzeit in 
python-Skripten keine entsprechende Funktion.

-QuotePlus(String)

Ruft urllib.quote_plus(String) auf, um ein URL-Encoding der Zeichenkette
zu erzeugen, damit diese in URLs verwendet werden kann. Zusätzlich werden 
als "+" codierte Leerzeichen in "%20" umcodiert. Zope bietet derzeit in
python-Skripten keine entsprechende Funktion.

-PKDateiname(String)

Ruft QuotePlus(string) auf und entfernt alle "%"-Zeichen in der 
resultierenden Zeichenkette. Zweck ist die Erzeugung funktionierender 
Verzeichnisnamen für die Z-Object-Database aus beliebigen Zeichenketten.

-GeheZuObjekt(Container,Objektnamensliste)

Durchwandert vom Container als Startpunkt die Objektnamensliste und sucht 
nach entsprechenden Sub-Objekten. Falls alle Objekte gefunden wurden, wird 
das "unterste" zurückgegeben. Ansonsten ist der Rückgabewert None.

-HoleObjekt(Zielverzeichnis)

Arbeitet wie GeheZuObjekt. Zielverzeichnis muss ein absoluter Pfad auf dem 
Zope-Server sein (z.B. /Examples/index_html).

-HoleZufallszahl(start,stop,step)

Ruft random.randrange(start,stop,step) auf, welches eine Zufallszahl aus 
dem angegebenen Bereich mit entsprechender Schrittweite zurückgibt. Zope 
bietet derzeit in python-Skripten keine entsprechende Funktion.

-VolleUrl()

Gibt die volle URL des aktuellen Requests aus: 

http://ServerName/Pfad?QUERY_STRING

Falls das erste Element des Pfads mit dem Servernamen übereinstimmt, wird 
es entfernt. Zweckmäßig für das Hosting mehrerer Websites auf einem 
Zope-Server.

Ist dem Pfad außerdem noch ein /SSL vorangestellt, wird dieses entfernt 
und https://ServerName/Pfad?QUERY_STRING als Ergebnis geliefert.  
Zweckmäßig um SSL-Requests von normalen zu unterscheiden und automatisch 
korrekt zu verlinken. Voraussetzung ist, dass Zope nicht der "richtige" 
Webserver ist und der "richtige" Webserver bei SSL-Requests automatisch 
das /SSL einschiebt.

-Base()

Gibt die volle Url des aktuellen Verzeichnisses aus.

3.	Formularfunktionen

Die Funktion SpeichereFormularDaten(formularname,neuAnlegen=0) speichert die 
Formulardaten des aktuellen Requests in einem Dictionary namens 
Formularname in der aktuellen Session ab. Außerdem wird der Wert von 
REQUEST.SESSION["formular"] auf formularname gesetzt.

Mit Hilfe von Formularwert(name) lassen sich danach die einzelnen Werte 
bestimmen. Gibt es den entsprechenden key name nicht, wird '' zurückgegeben.

Das optionale Argument neuAnlegen bestimmt, ob ein evtl. schon in der Session
vorhandenes Dictionary vorher gelöscht wird. Dies wird benötigt, wenn einmal
aktivierte Checkboxen in Formularen auch wieder deaktiviert werden sollen können.

Beispiel
--------

-Legen Sie eine DTML-Methode Formular mit folgendem Inhalt an:

<form action=Ergebnis>
<pre>
Vorname: <input type="text" name="vorname" value="<dtml-var 
expr=Formularwert('vorname')>">
Nachname: <input type="text" name="nachname" value="<dtml-var 
expr=Formularwert('nachname')>">
<input type="submit" name="submit" value="Abschicken">
</pre>
</form>

-Legen Sie ein Python-Skript PruefeFormular mit folgendem Inhalt an:

if context.Formularwert('vorname')=='': return 'Vorname leer'
if context.Formularwert('nachname')=='': return 'Nachname leer'
return ''

-Legen Sie eine DTML-Methode Ergebnis mit folgendem Inhalt an:

<dtml-call expr="SpeichereFormularDaten('bla')">
<dtml-if PruefeFormular>
 FEHLER: <dtml-var PruefeFormular>
 <dtml-var Formular>
<dtml-else>
Vorname: <dtml-var expr=Formularwert('vorname')>
Nachname: <dtml-var expr=Formularwert('nachname')>
</dtml-if>

-Legen Sie eine DTML-Methode Formularstart mit folgendem Inhalt an:

<dtml-call expr="SpeichereFormularDaten('bla')">
<dtml-var Formular>