Flexible Verarbeitung der Formular-Daten

Rückmeldungs-Element instant_form_feedback

Auf 'instant_form' haben Sie angegeben, welche Seite zur Auswertung der Formular-Eingabe aufgerufen werden soll. Damit diese Seite tatsächlich diese Eingaben auswerten kann, muss es z.B. die External Source 'instant_form_feedback' enthalten. Diese External Source wertet die Eingabe aus und ruft danach ein Skript auf, welches die Eingabe weiterverwendet. In diesem Skript (referenziert durch den zweiten Parameter) können Sie die weitere Verarbeitung der eingegebenen Daten frei steuern. Sie können die Daten in einem Mail verschicken und zusätzlich eine Bestätigungsmail an den Kunden versenden, Sie können die Daten in einer Datenbank speichern etc.
Diese External Source hat vier Parameter:

ID of the Formulator form [optional]

Hier muss die ID des gleichen Formulars eingegeben werden wie im ersten 'External Source'-Element.

ID of the script to process the form's input [optional]

Mit diesem Parameter können Sie das Skript angeben, welches die Eingabe verarbeiten soll (post-processing).

ID of the script for confirmation [optional]

Mit diesem Parameter können Sie das Skript bezeichnen, welches die Bestätigungsseite aufbereitet (pre-processing).

Label of confirmation button [optional]

Mit diesem Parameter können Sie die Beschriftung der Schaltfläche steuern, die auf der Bestätigungsseite eingeblendet wird. Falls dieses Feld leer ist, wird standardmässig 'Bestätigen' (für deutsche Dokumente) bzw. 'Confirm (für englische Dokumente) eingeblendet.

Mit diesen Parametern können Sie steuern, wie die Eingabe verarbeitet wird. Wenn Sie die beiden letzten Parameter (bezüglich Bestätigung) leer lassen, so wird keine Bestätitungsseite eingeblendet. Die Eingabe wird nach Betätigen der Senden-Schaltfläche sofort vom Verarbeitungs-Skript (gemäss zweitem Parameter oder standardmässig) ausgewertet.

Hinweise zu den Verarbeitungs-Skripten

Die Aufgabe dieser Skripte ist, die Eingabe aus dem Formular zu verarbeiten und eine sinnvolle Meldung zurückzugeben. Sie können mit der return Anweisung einen html-formatierten Text zurückgeben, welcher in der Folge auf dem dem Silva-Dokument an der Stelle des Bestätigungs-Elements angezeigt wird.

Die Skripte müssen genau einen Parameter besitzen. Mit diesem Parameter werden den Skripten ein Resultat-Objekt übergeben. Dieses Resultat-Objekt ermöglicht den Zugriff auf die Formular-Daten.

API des Resultat-Objekts:

get_fields():

Diese Methode gibt eine Liste der Formular-Felder zurück. Die Listenelemente sind in der Reihenfolge der Felder auf dem Formular. Jedes Listenelement besteht aus dem Tupel (id, title, value).

fields():

Diese Methode gibt ein Verzeichnis (Dictionary) aller Felder zurück. Sie können diese Methode verwenden, um über die Feld-ID direkt auf die Feld-Daten zuzugreifen. Jeder Eintrag in diesem Verzeichnis enthält wieder ein Dictionary in der Form {'value':value, 'title':title}.

get_mailbody():

Dies ist eine Komfort-Methode. Sie gibt ein einen String zurück, welcher alle Felder-Titel: Feld-Werte enthält. Dieser String ist geeignet formatiert, dass er in einer Bestätigungs-Mail verschickt werden kann.

get_errors():

Diese Methode enthält allfällige Meldungen, die bei der Validierung der Eingabe erzeugt werden. Der Text ist html-formatiert.

isBotSuspect():

Mit dieser Methode kann abgefragt werden, ob das Formular durch ein Webbot aufgefüllt worden ist. Gibt die Methode 'true' zurück, kann die weitere Verarbeitung der Formular-Eingabe abgebrochen werden.

Mit Hilfe des Resultat-Objekts können Sie wie folgt auf die Felder zugreifen (Annahme: Der Parameter heisse 'result_obj', die ID des Eingabefelds sei 'mail_from'):

result_obj.fields()['mail_from']['value']

gibt die Benützer-Eingabe in das Feld 'mail_from' zurück.

result_obj.fields()['mail_from']['title']

gibt den Titel des Felds 'mail_from' auf dem Formular zurück (z.B. 'Absenderadresse').
Wenn das Eingabefeld für 'mail_from' allerdins kein zwingendes Formularfeld ist, so führt der Zugriff result_obj.fields()['mail_from'] unter Umständen zu einem Fehler. In solchen Fällen empfiehlt sich folgende Variante:

field = result_obj.fields().get('mail_from', {'value':'', 'title':''})

Der Zugriffsmethode wird ein optionales Argument zugefügt, welches zurückgegeben wird, wenn das Dictionary keinen Eintrag mit dem Schlüssel 'mail_from' enthält. Auf diese Weise ist sichergestellt, dass die Variable 'field' ein Dictionary mit den beiden Einträgen 'value' und 'title' enthält.

Beispiel eines Verarbeitungs-Skripts (post-processing)

##parameters=result_obj
##title=Script to process form input
from Products.SilvaExtETHLayout.helpers import send_mail

if result_obj.isBotSuspect():
    return ''

mail_to = u'helpdesk@id.ethz.ch'
fields = result_obj.fields()
mail_from = fields.get('mail_from', {'value':u'', 'title':u''})['value']
mail_subject = u'[WCMS] Beispiel für Verarbeitungs-Skript'
mail_text = u'Beispiel für Verarbeitungs-Skript\n\n'
mail_text += result_obj.get_mailbody()

result = send_mail(context, mail_to, mail_from, mail_subject, mail_text)
if result:
    return '<p>%s</p>' %result

out_html = ''
for id, title, value in result_obj.get_fields():
    if value:
        out_html += u'<i>%s</i>: %s<br />' %(title, value)

#Send confirmation to user's address
if mail_from:
    result = send_mail(context, mail_from, mail_from, mail_subject, mail_text)

out = u'<p>Das Formular mit folgendem Inhalt wurde abgeschickt:</p><p>%s</p>'
return out %out_html 

Dem Skript werden im Parameter 'result_obj' die eingegebenen Werte aus dem Formular übergeben. Mit diesen Eingaben werden die Variable mait_to etc. initialisiert. Das Skript prüft dabei, ob die Felder wirklich vorhanden sind. Mit diesen Eingaben soll ein Mail an das Helpdesk geschickt werden. Zu diesem Zweck wird die Funktion send_mail importiert und aufgerufen. Sind Probleme beim Abschicken der Mail aufgetreten, so gibt die Funktion eine entsprechende Fehlermeldung zurück. Im Erfolgsfall wird ein Leerstring zurückgegeben. Danach wird zur Bestätigung eine Mail an den Sender geschickt. Am Schluss des Skripts wird eine Meldung formatiert und mit return zurückgegeben.
Bemerkung: Alle Strings im Skript sind Unicode (mit Hilfe von u'Text ...'), ebenso die Werte, welche das 'result_obj' liefert.

Die Methode send_mail steht standardmässig zur Verfügung. Sie spricht den auf dem System konfigurierten Mail-Host an kann mit Products.SilvaExtETHLayout.helpers importiert werden.

Beispiel für ein Skript, welches die Bestätigungs-Seite vorbereitet:

##parameters=result_obj
##title=Script to prepare the confirmation page
out_html = ''
for id, title, value in result_obj.get_fields():
    if value:
        out_html += '<i>%s</i>: %s<br />' %(title, value)

return out_html + '<p>&nbsp;</p>'