\r
<html xmlns="http://www.w3.org/1999/xhtml">\r
<head>\r
-<title>ReadMe für Form E-Mail 3.4.1</title>\r
+<title>ReadMe für Form E-Mail 3.5</title>\r
<meta name="author" content="Patrick Canterino" />\r
<style type="text/css">\r
<!--\r
padding-left: 0.5cm;\r
padding-right: 0.5cm;\r
}\r
+pre\r
+{\r
+ padding-left: 0.7cm;\r
+ padding-right: 0.7cm;\r
+ font-family: 'Courier New', Courier, monospace;\r
+ font-size: 10pt;\r
+ color: #0000B0;\r
+}\r
table\r
{\r
font-size: 10pt;\r
</head>\r
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#0000FF" alink="#0000FF">\r
\r
-<h1><a name="top" id="top">ReadMe für Form E-Mail 3.4.1</a></h1>\r
+<h1><a name="top" id="top">ReadMe für Form E-Mail 3.5</a></h1>\r
\r
<p>\r
<a href="#wasistfeml">Was ist <i>Form E-Mail</i>?</a><br />\r
<a href="#einrichten">Einrichten von <i>Form E-Mail</i></a><br />\r
<a href="#einstellungen">Einstellungen</a><br />\r
+<a href="#individuell">Individuelle Formularfelder</a><br />\r
<a href="#templates">Templates anpassen</a>\r
</p>\r
\r
<p>Sie können außerdem noch ein Feld namens <i>subject</i> anlegen. Hier kann ein Betreff für die Mail eingegeben werden. Wenn Sie auf dieses Feld verzichten, erhalten die E-Mails automatisch den in <code>$default_subject</code> definierten Betreff (s.u.).<br />\r
Weiterhin ist noch ein Feld namens <i>recipient</i> möglich. Dieses Feld enthält einen Alias-Empfänger. Wie das funktioniert, können Sie bei der Beschreibung der Einstellung <code>$aliases</code> lesen.</p>\r
\r
+<p>Zusätzlich können Sie die vorgegebenen Formularfelder mit <a href="#individuell">individuellen</a> ergänzen.</p>\r
+\r
<p>Wenn Sie Captchas (zufällige Zeichenfolgen, die der Benutzer vor dem Absenden des Formulars eingeben muss, um Spambots auszuschließen) benutzen wollen (siehe unten), müssen Sie im Formular die Datei <i>captcha.php</i> als Bild einbinden (<code><img></code>-Tag). Bedenken Sie, dass Sie diese Datei auch in den <a href="#templates">Templates</a> einbinden müssen!</p>\r
\r
-<p>Das Formular muss noch die Daten an die Datei <i>mailer.php</i> (oder wie Sie die Datei genannt haben) senden. Ob Sie dafür <tt>GET</tt> oder <tt>POST</tt> verwenden, ist egal (es sei denn, Sie haben <i>Form E-Mail</i> so eingestellt, dass es nur <tt>POST</tt> erlaubt).</p>\r
+<p>Das Formular muss dann noch mit <tt>POST</tt> die Daten an die Datei <i>mailer.php</i> (oder wie Sie die Datei genannt haben) senden.</p>\r
\r
<p>Ein beispielhaftes Formular finden Sie in der Datei <a href="formular.htm" target="_blank"><i>formular.htm</i></a>.</p>\r
\r
\r
<p>Geben Sie zwischen den einfachen Anführungszeichen die Adresse an, an die die Mail gehen soll. Wenn die Mail an mehrere Empfänger gehen soll, so trennen Sie die einzelnen E-Mail-Adressen ganz einfach durch Semikolons.</p>\r
\r
-<p>Das war es im Grunde genommen. Aber <i>Form E-Mail</i> lässt sich noch weiter konfigurieren. Mehr dazu finden Sie in den nächsten beiden Abschnitten.</p>\r
+<p>Sie haben nun <i>Form E-Mail</i> für die Standard-Nutzung konfiguriert. <i>Form E-Mail</i> lässt sich jedoch noch feiner konfigurieren. Mehr dazu finden Sie in den nächsten Abschnitten.</p>\r
\r
<p class="upanddown"><a href="#top">Nach oben</a></p>\r
\r
<td><code>$aliases</code></td>\r
<td>Hier können Sie eine Alias-Namen für Empfänger angeben. Soll einem Alias mehrere Empfänger zugeordnet werden, gilt dasselbe wie für <code>$mailto</code>.<br />\r
Die Aliase werden mit Hilfe eines assoziativen PHP-Arrays definiert. Da es wohl einige gibt, die von so etwas keine Ahnung haben und ich es nicht gut erklären kann, hier ein Beispiel:<br /><br />\r
-<code>array('info' => 'info@IhreDomain.xyz', 'support' => 'support@IhreDomain.xyz',<br />\r
- 'alle' => 'info@IhreDomain.xyz; support@IhreDomain.xyz')</code></td>\r
+<code>array('info' => 'info@example.com', 'support' => 'support@example.com',<br />\r
+ 'alle' => 'info@example.com; support@example.com')</code></td>\r
</tr>\r
</table>\r
\r
</tr>\r
<tr>\r
<td><code>$friendly_sender</code></td>\r
-<td>Wenn 1, wird die E-Mail-Adresse des Autors der Mail als Absender angegeben. Bei 0 erscheint das, was der Server als Absender einträgt. Wenn 2, wird zusätzlich noch der Name als Absender angegeben.<br />\r
+<td>Wenn 1, wird die E-Mail-Adresse des Autors der Mail als Absender angegeben. Bei 0 erscheint das, was der Server als Absender einträgt und die E-Mail-Adresse des Absenders wird in den <code>Reply-To</code>-Header eingetragen, so dass beim Antworten auf die E-Mail schon der richtige Empfänger eingetragen wird. Wenn 2, wird zusätzlich noch der Name als Absender angegeben.<br />\r
Bitte setzen Sie diese Option nur auf 0, wenn es wirklich sein muss!</td>\r
</tr>\r
<tr>\r
<b style="color:#FF0000">Achtung:</b> Benutzen Sie hier nach Möglichkeit absolute URLs! Ich habe zwar etwas eingebaut, was hier relative URLs in absolute umwandelt, um dem HTTP-Standard gerecht zu werden, aber ich garantiere nicht, dass diese Umwandlung immer einwandfrei funktioniert. Seien Sie bei relativen URLs also sehr vorsichtig und verwenden Sie im Fehlerfall absolute.</td>\r
</tr>\r
<tr>\r
-<td><code>$no_tld</code></td>\r
-<td>Setzen Sie diese Option auf 1, wenn der Absender auch E-Mail-Adressen ohne Top-Level-Domain angeben darf.</td>\r
-</tr>\r
-<tr>\r
<td><code>$allowed_envs</code></td>\r
<td>Geben Sie hier die Server-Umgebungsvariablen, die im Mailtext angezeigt werden dürfen, als normales PHP-Array an (siehe auch die Erläuterungen zur Template-Datei <i>mail.txt</i>).<br />\r
Beispiel: <code>array('HTTP_USER_AGENT','REMOTE_ADDR')</code></td>\r
<td><b>Beschreibung</b></td>\r
</tr>\r
<tr>\r
-<td><code>$only_post</code></td>\r
-<td>Wenn > 0, kann <i>Form E-Mail</i> nur mit der HTTP-Zugriffsmethode <tt>POST</tt> aufgerufen werden</td>\r
-</tr>\r
-<tr>\r
<td><code>$check_referer</code></td>\r
<td>Wenn > 0, überprüft <i>Form E-Mail</i> die Host-Angabe im HTTP-Referer. Das ist nützlich, wenn Sie verhindern wollen, dass irgendjemand Ihr Script für sich ausnutzt.</td>\r
</tr>\r
<tr>\r
<td><code>$referer_ok</code></td>\r
-<td>Geben Sie hier die Hosts an, von denen <i>Form E-Mail</i> aus aufgerufen werden darf (zum Beispiel <i>www.IhreDomain.xyz</i>). Trennen Sie mehrere Hosts durch Semikolons.<br />\r
+<td>Geben Sie hier die Hosts an, von denen <i>Form E-Mail</i> aus aufgerufen werden darf (zum Beispiel <i>www.example.com</i>). Trennen Sie mehrere Hosts durch Semikolons.<br />\r
<b style="color:#FF0000">Achtung:</b> Mit einer Referer-Prüfung kann man zwar unbedarfte Anwender abschrecken, aber wirklich zuverlässig ist diese Methode nicht, da sich der Referer fälschen lässt oder auch komplett fehlen kann.</td>\r
</tr>\r
</table>\r
\r
+<p><b>Mails speichern</b></p>\r
+\r
+<table border="1">\r
+<tr>\r
+<td><b>Einstellung</b></td>\r
+<td><b>Beschreibung</b></td>\r
+</tr>\r
+<tr>\r
+<td><code>$store_mails</code></td>\r
+<td>Wenn > 0, speichert <i>Form E-Mail</i> die Mails nach dem Versenden noch auf dem Server als Datei ab.</td>\r
+</tr>\r
+<tr>\r
+<td><code>$store_mails_dir</code></td>\r
+<td>Geben Sie hier das Verzeichnis an, in dem <i>Form E-Mail</i> die Mails speichern soll (Standard ist <i>stored_mails</i>). Die Dateinamen bestehen aus dem Präfix, dem Absender, dem Betreff, der Uhrzeit und einem eindeutigen Wert.</td>\r
+</tr>\r
+<tr>\r
+<td><code>$store_mails_prefix</code></td>\r
+<td>Geben Sie hier einen Präfix an, der den Dateinamen der gespeicherten Mails vorangestellt werden soll (Standard ist <i>feml_</i>).</td>\r
+</tr>\r
+<tr>\r
+<td><code>$store_mails_max</code></td>\r
+<td>Geben Sie hier die Zahl der Mails an, die maximal aufbewahrt werden sollen. Wenn Sie hier 0 angeben, werden keine Mails gelöscht. Die Mail-Dateien werden anhand des mit <code>$store_mails_prefix</code> definierten Präfixes erkannt.</td>\r
+</tr>\r
+</table>\r
+\r
<p><b>Captchas</b></p>\r
\r
<table border="1">\r
<td>Der vom Benutzer eingegebene Text ist nicht lang genug</td>\r
</tr>\r
<tr>\r
+<td><code>$err_name_long</code></td>\r
+<td>Der vom Benutzer eingegebene Name ist nicht zu lang</td>\r
+</tr>\r
+<tr>\r
+<td><code>$err_subject_long</code></td>\r
+<td>Der vom Benutzer eingegebene Betreff ist zu lang</td>\r
+</tr>\r
+<tr>\r
+<td><code>$err_text_long</code></td>\r
+<td>Der vom Benutzer eingegebene Text ist zu lang</td>\r
+</tr>\r
+<tr>\r
<td><code>$err_send_error</code></td>\r
<td>Die Mail konnte nicht versendet werden</td>\r
</tr>\r
<tr>\r
+<td><code>$err_store_error</code></td>\r
+<td>Die Mail konnte nicht gespeichert werden</td>\r
+</tr>\r
+<tr>\r
<td><code>$err_only_post</code></td>\r
<td><i>Form E-Mail</i> darf nur mit <tt>POST</tt> aufgerufen werden</td>\r
</tr>\r
<td>Der im HTTP-Referer angegebene Host darf keine Mails über das Script senden</td>\r
</tr>\r
<tr>\r
+<td><code>$err_indiv_errmsg_miss</code></td>\r
+<td>Eine Fehlermeldung für die individuellen Formularfelder wurde nicht definiert (die Variable <code>{INDIVIDUAL}</code> gibt das Formularfeld an, <code>{ERRMSG}</code> die fehlende Fehlermeldung).</td>\r
+</tr>\r
+<tr>\r
<td><code>$err_captcha_incorrect</code></td>\r
<td>Der vom Benutzer eingegebene Captcha-Code ist nicht korrekt</td>\r
</tr>\r
\r
<p class="upanddown"><a href="#top">Nach oben</a></p>\r
\r
+<h2><a name="individuell" id="individuell">Individuelle Formularfelder</a></h2>\r
+\r
+<p>Seit Version 3.5 ist es möglich, in <i>Form E-Mail</i> zusätzlich zu den vorgegebenen Formularfeldern für Name, E-Mail-Adresse, Betreff und Text eigene Formularfelder zu definieren, die dann von <i>Form E-Mail</i> verarbeitet und in die Mail eingefügt werden.<br />\r
+Wie <i>Form E-Mail</i> diese Formularfelder behandelt, wird über verschiedene Optionen gesteuert, so ist es möglich die Länge des Inhalts zu prüfen, den Inhalt gegen einen regulären Ausdruck und gegen eine frei definierbare PHP-Funktion zu prüfen und am Ende den Inhalt noch durch eine PHP-Funktion aufzubereiten.</p>\r
+\r
+<p>Die Konfiguration der individuellen Formularfelder geschieht über das PHP-Array <code>$user_fields</code> in <i>config.php</i>. Sie benötigen zunächst den Namen des Formularfeldes, also das, was Sie im HTML-Formular als Namen angeben. Nehmen wir an, Sie haben folgenden HTML-Code für ein Formularfeld:</p>\r
+\r
+<p><code><input type="text" name="beruf" /></code></p>\r
+\r
+<p>Der Name des Feldes lautet also <b>beruf</b>. Dies benötigen wir für die weitere Definition.</p>\r
+\r
+<p>Sie können nun verschiedene Prüfwerte definieren, mit denen <i>Form E-Mail</i> den Inhalt des Formularfeldes überprüft und ggf. eine Fehlermeldung ausgibt. Diese werden in der folgenden Tabelle erläutert (die Tabelle geht der Einfachheit halber weiterhin vom Formularfeld <b>beruf</b> aus - Sie müssen dies natürlich anpassen!):</p>\r
+\r
+<table border="1">\r
+<tr>\r
+<td><b>Einstellung</b></td>\r
+<td><b>Beschreibung</b></td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['min']</code></td>\r
+<td>Geben Sie hier an, wie lang der vom Benutzer eingebene Wert mindestens sein muss</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['max']</code></td>\r
+<td>Geben Sie hier an, wie lang der vom Benutzer eingebene Wert höchstens sein darf</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['required']</code></td>\r
+<td>Geben Sie hier den Wert 1 an, wenn das Formularfeld ausgefüllt sein muss. Wenn Sie hier eine 0 oder die Option weglassen, ist das Feld optional.</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['regex']</code></td>\r
+<td>Geben Sie hier einen <a href="http://de.php.net/manual/de/book.pcre.php">Perl-kompatiblen regulären Ausdruck</a> zur Prüfung des Wertes ein. Der Ausdruck wird direkt an <a href="http://de.php.net/manual/de/function.preg-match.php"><code>preg_match()</code></a> weitergegeben.</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['check']</code></td>\r
+<td>Geben Sie hier eine selbst definierte PHP-Funktion (als Zeichenkette) an, durch die der Wert geprüft werden soll. Das erste und einzige Argument der Funktion ist der Inhalt des Formularfeldes. Die Funktion muss <code>true</code> zurückgeben, wenn der Wert in Ordnung ist, ansonsten <code>false</code>.</td>\r
+</tr>\r
+</table>\r
+\r
+<p>Weiterhin müssen Sie noch diverse Fehlermeldungen definieren (als Unter-Array). Das Definieren dieser Fehlermeldungen ist Pflicht (Sie müssen jedoch nur die Fehlermeldungen zu den Dingen definieren, die auch wirklich geprüft werden).</p>\r
+\r
+<table border="1">\r
+<tr>\r
+<td><b>Einstellung</b></td>\r
+<td><b>Beschreibung</b></td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['errors']['too_short']</code></td>\r
+<td>Der vom Benutzer eingegebene Wert ist nicht lang genug</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['errors']['too_long']</code></td>\r
+<td>Der vom Benutzer eingegebene Wert ist zu lang</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['errors']['not_set']</code></td>\r
+<td>Das Formularfeld ist ein Pflichtfeld und es wurde nicht ausgefüllt.</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['errors']['match_fail']</code></td>\r
+<td>Die Überprüfung des Wertes durch den regulären Ausdruck ist fehlgeschlagen.</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['errors']['check_fail']</code></td>\r
+<td>Die Überprüfung des Wertes durch die PHP-Funktion ist fehlgeschlagen.</td>\r
+</tr>\r
+</table>\r
+\r
+<p>Zusätzlich sind noch die folgenden Einstellungen möglich:</p>\r
+\r
+<table border="1">\r
+<tr>\r
+<td><b>Einstellung</b></td>\r
+<td><b>Beschreibung</b></td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['prepare']</code></td>\r
+<td>Geben Sie hier eine selbst definierte PHP-Funktion (als Zeichenkette) an, die den Wert des Formularfeldes nach den Prüfungen noch verändern (bspw. kann man hier Funktionen angeben, die alle Buchstaben in Großbuchstaben umwandelt). Das erste und einzige Argument der Funktion ist der Inhalt des Formularfeldes. Die Funktion muss den bearbeiteten Wert zurückgeben.</td>\r
+</tr>\r
+<tr>\r
+<td><code>$user_fields['beruf']['tpl_var']</code></td>\r
+<td>Geben Sie hier die <a href="#templates">Template-Variable</a> an, die in den Templates durch den Wert des Formularfeldes ersetzt werden soll. Wenn Sie hier nichts angeben, wird ein Standardwert verwendet (im Fall des Formularfeldes <b>beruf</b> wäre das dann <code>USER_beruf</code>).</td>\r
+</tr>\r
+</table>\r
+\r
+<p>Sie müssen die individuellen Formularfelder nun noch in Ihrem Mail-Formular und in den <a href="#templates">Templates</a> ergänzen.</p>\r
+\r
+<p>Es folgt Beispiel-Konfiguration für ein Formularfeld namens <i>beruf</i>:</p>\r
+\r
+<pre>\r
+$user_fields['beruf']['min'] = 5;\r
+$user_fields['beruf']['max'] = 10;\r
+$user_fields['beruf']['required'] = 1;\r
+$user_fields['beruf']['regex'] = '/^[A-Za-z]+$/';\r
+$user_fields['beruf']['check'] = 'check_beruf';\r
+$user_fields['beruf']['prepare'] = 'prepare_beruf';\r
+$user_fields['beruf']['tpl_var'] = 'BERUF';\r
+\r
+$user_fields['beruf']['errors']['too_short'] = 'Der Beruf muss mind. 5 Zeichen lang sein!';\r
+$user_fields['beruf']['errors']['too_long'] = 'Der Beruf darf höchstens 10 Zeichen lang sein!';\r
+$user_fields['beruf']['errors']['not_set'] = 'Sie haben keinen Beruf eingegeben!';\r
+$user_fields['beruf']['errors']['match_fail'] = 'Der Beruf darf nur aus Buchstaben bestehen!';\r
+$user_fields['beruf']['errors']['check_fail'] = 'Der Beruf sollte keine äöü haben!';\r
+\r
+# Beispiel-Check-Funktion\r
+\r
+function check_beruf($content) {\r
+ if(strpos($content,'ä') !== false) return false;\r
+ if(strpos($content,'ö') !== false) return false;\r
+ if(strpos($content,'ü') !== false) return false;\r
+ \r
+ return true;\r
+}\r
+\r
+# Beispiel-Vorbereitungs-Funktion\r
+\r
+function prepare_beruf($content) {\r
+ return strtolower($content);\r
+}\r
+</pre>\r
+\r
+<p>Das Formularfeld hat die folgenden Eigenschaften:</p>\r
+\r
+<ul>\r
+<li>Der Beruf muss aus mind. 5 Zeichen und max. 10 Zeichen bestehen (<code>min</code> und <code>max</code>)</li>\r
+<li>Das Formularfeld ist ein Pflichtfeld (<code>required</code>)</li>\r
+<li>Es sind nur die Buchstaben A-Z (groß und klein) erlaubt (<code>regex</code>)</li>\r
+<li>Über die Prüffunktion <code>check_beruf()</code> wird verhindert, dass ä, ö und ü angegeben werden (das wird natürlich auch durch den regulären Ausdruck ausgeschlossen, es soll lediglich zur Verdeutlichung dienen)</li>\r
+<li>Durch die Vorbereitungsfunktion <code>prepare_beruf()</code> werden alle Großbuchstaben in Kleinbuchstaben umgewandelt</li>\r
+<li>In den Templates wird die Variable <code>{BERUF}</code> durch den Inhalt des Formularfeldes ersetzt (<code>tpl_var</code>)</li>\r
+<li>Die Fehlermeldungen sollten selbsterklärend sein</li>\r
+</ul>\r
+\r
+<p class="upanddown"><a href="#top">Nach oben</a></p>\r
+\r
<h2><a name="templates" id="templates">Templates anpassen</a></h2>\r
\r
<p>Die Anpassung der Ausgaben von <i>Form E-Mail</i> erfolgt über Templates (englisch für "Vorlagen"). Jede der Templates enthält Variablen der Form <b>{VARIABLENNAME}</b>, die dann von <i>Form E-Mail</i> durch entsprechende Daten ersetzt werden.</p>\r
Die formatierte Zeitangabe</li>\r
</ul>\r
\r
+Weiterhin können Sie hier die definierten Variablen der <a href="#individuell">individuellen Formularfelder</a> (das, was Sie in <code>tpl_var</code> angegeben haben) verwenden.<br />\r
+<br />\r
Zusätzlich können Sie hier durch Variablen, die mit <b>ENV_</b> beginnen, Server-Umgebungsvariablen im Text einfügen (siehe auch Konfigurationsvariable <code>$allowed_envs</code>.\r
</td>\r
</tr>\r
<li><b>TIME</b><br />\r
Die formatierte Zeitangabe</li>\r
</ul>\r
+\r
+Weiterhin können Sie hier die definierten Variablen der <a href="#individuell">individuellen Formularfelder</a> (das, was Sie in <code>tpl_var</code> angegeben haben) verwenden.\r
</td>\r
</tr>\r
<tr>\r
Der eingegebene Mail-Text</li>\r
</ul>\r
\r
+Weiterhin können Sie hier die definierten Variablen der <a href="#individuell">individuellen Formularfelder</a> (das, was Sie in <code>tpl_var</code> angegeben haben) verwenden.<br />\r
+<br />\r
Zusätzlich ist es möglich, einen Bereich, der nur angezeigt werden soll, wenn Captchas aktiviert sind, anzuzeigen, indem Sie diesen in folgenden Block einschließen (der <code>{ELSE}</code>-Teil ist optional):<br />\r
<br />\r
<code>{IF CAPTCHA}Captchas sind aktiviert{ELSE}Captchas sind nicht aktiviert{ENDIF}</code>\r
\r
<hr width="80%" noshade="noshade" />\r
\r
-<p style="font-size:8pt">© 2002-2011 Patrick Canterino</p>\r
+<p style="font-size:8pt">© 2002-2012 Patrick Canterino</p>\r
\r
<table border="0" cellspacing="0" style="font-size:8pt">\r
<tr>\r
git.p6c8.net / form-email.git / blobdiff