X-Git-Url: https://git.p6c8.net/form-email.git/blobdiff_plain/d1446fd17368b3db10988069662a18386fe587a8..1083cc6dc155417c3619e538e657df3845b9ee97:/readme.htm

diff --git a/readme.htm b/readme.htm
index de71bcc..7604cae 100644
--- a/readme.htm
+++ b/readme.htm
@@ -22,14 +22,12 @@ a:link, a:visited, a:active, a:focus
  font-weight: normal;
  text-decoration: none;
  color: #0000FF;
- cursor: hand;
 }
 a:link:hover, a:visited:hover, a:active:hover, a:focus:hover
 {
  font-weight: normal;
  text-decoration: underline;
  color: #0000FF;
- cursor: hand;
 }
 body
 {
@@ -65,6 +63,14 @@ p
  padding-left: 0.5cm;
  padding-right: 0.5cm;
 }
+pre
+{
+ padding-left: 0.7cm;
+ padding-right: 0.7cm;
+ font-family: 'Courier New', Courier, monospace;
+ font-size: 10pt;
+ color: #0000B0;
+}
 table
 {
  font-size: 10pt;
@@ -130,6 +136,8 @@ Auf diese Weise müssen Sie zum Beispiel nicht überall auf Ihrer Homepa
 <p>Sie k&ouml;nnen au&szlig;erdem noch ein Feld namens <i>subject</i> anlegen. Hier kann ein Betreff f&uuml;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 />
 Weiterhin ist noch ein Feld namens <i>recipient</i> m&ouml;glich. Dieses Feld enth&auml;lt einen Alias-Empf&auml;nger. Wie das funktioniert, k&ouml;nnen Sie bei der Beschreibung der Einstellung <code>$aliases</code> lesen.</p>
 
+<p>Zus&auml;tzlich k&ouml;nnen Sie die vorgegebenen Formularfelder mit <a href="#individuell">individuellen</a> erg&auml;nzen.</p>
+
 <p>Wenn Sie Captchas (zuf&auml;llige Zeichenfolgen, die der Benutzer vor dem Absenden des Formulars eingeben muss, um Spambots auszuschlie&szlig;en) benutzen wollen (siehe unten), m&uuml;ssen Sie im Formular die Datei <i>captcha.php</i> als Bild einbinden (<code>&lt;img&gt;</code>-Tag). Bedenken Sie, dass Sie diese Datei auch in den <a href="#templates">Templates</a> einbinden m&uuml;ssen!</p>
 
 <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>
@@ -142,7 +150,7 @@ Weiterhin ist noch ein Feld namens <i>recipient</i> m&ouml;glich. Dieses Feld en
 
 <p>Geben Sie zwischen den einfachen Anf&uuml;hrungszeichen die Adresse an, an die die Mail gehen soll. Wenn die Mail an mehrere Empf&auml;nger gehen soll, so trennen Sie die einzelnen E-Mail-Adressen ganz einfach durch Semikolons.</p>
 
-<p>Das war es im Grunde genommen. Aber <i>Form E-Mail</i> l&auml;sst sich noch weiter konfigurieren. Mehr dazu finden Sie in den n&auml;chsten beiden Abschnitten.</p>
+<p>Sie haben nun <i>Form E-Mail</i> f&uuml;r die Standard-Nutzung konfiguriert. <i>Form E-Mail</i> l&auml;sst sich jedoch noch feiner konfigurieren. Mehr dazu finden Sie in den n&auml;chsten Abschnitten.</p>
 
 <p class="upanddown"><a href="#top">Nach oben</a></p>
 
@@ -163,8 +171,9 @@ Weiterhin ist noch ein Feld namens <i>recipient</i> m&ouml;glich. Dieses Feld en
 <td><code>$aliases</code></td>
 <td>Hier k&ouml;nnen Sie eine Alias-Namen f&uuml;r Empf&auml;nger angeben. Soll einem Alias mehrere Empf&auml;nger zugeordnet werden, gilt dasselbe wie f&uuml;r <code>$mailto</code>.<br />
 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&auml;ren kann, hier ein Beispiel:<br /><br />
-<code>array('info' =&gt; 'info@IhreDomain.xyz', 'support' =&gt; 'support@IhreDomain.xyz',<br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'alle' =&gt; 'info@IhreDomain.xyz; support@IhreDomain.xyz')</code></td>
+<code>array('info' =&gt; 'info@example.com', 'support' =&gt; 'support@example.com',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'alle' =&gt; 'info@example.com; support@example.com')</code><br /><br />
+Sie m&uuml;ssen nun in Ihrem Formular ein Feld namens <i>recipient</i> einf&uuml;gen, &uuml;ber das Sie den Alias-Empf&auml;nger angeben (beispielsweise k&ouml;nnen Sie hier eine <code>&lt;select&gt;</code>-Box verwenden, &uuml;ber das der Benutzer den Empf&auml;nger ausw&auml;hlen kann).</td>
 </tr>
 </table>
 
@@ -264,7 +273,7 @@ Beispiel: <code>array('HTTP_USER_AGENT','REMOTE_ADDR')</code></td>
 </tr>
 <tr>
 <td><code>$referer_ok</code></td>
-<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 />
+<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 />
 <b style="color:#FF0000">Achtung:</b> Mit einer Referer-Pr&uuml;fung kann man zwar unbedarfte Anwender abschrecken, aber wirklich zuverl&auml;ssig ist diese Methode nicht, da sich der Referer f&auml;lschen l&auml;sst oder auch komplett fehlen kann.</td>
 </tr>
 </table>
@@ -407,10 +416,26 @@ Beispiel: <code>array('HTTP_USER_AGENT','REMOTE_ADDR')</code></td>
 <td>Der vom Benutzer eingegebene Text ist nicht lang genug</td>
 </tr>
 <tr>
+<td><code>$err_name_long</code></td>
+<td>Der vom Benutzer eingegebene Name ist nicht zu lang</td>
+</tr>
+<tr>
+<td><code>$err_subject_long</code></td>
+<td>Der vom Benutzer eingegebene Betreff ist zu lang</td>
+</tr>
+<tr>
+<td><code>$err_text_long</code></td>
+<td>Der vom Benutzer eingegebene Text ist zu lang</td>
+</tr>
+<tr>
 <td><code>$err_send_error</code></td>
 <td>Die Mail konnte nicht versendet werden</td>
 </tr>
 <tr>
+<td><code>$err_store_error</code></td>
+<td>Die Mail konnte nicht gespeichert werden</td>
+</tr>
+<tr>
 <td><code>$err_only_post</code></td>
 <td><i>Form E-Mail</i> darf nur mit <tt>POST</tt> aufgerufen werden</td>
 </tr>
@@ -472,6 +497,135 @@ Beispiel: <code>array('HTTP_USER_AGENT','REMOTE_ADDR')</code></td>
 <p>Seit Version&nbsp;3.5 ist es m&ouml;glich, in <i>Form E-Mail</i> zus&auml;tzlich zu den vorgegebenen Formularfeldern f&uuml;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&uuml;gt werden.<br />
 Wie <i>Form E-Mail</i> diese Formularfelder behandelt, wird &uuml;ber verschiedene Optionen gesteuert, so ist es m&ouml;glich die L&auml;nge des Inhalts zu pr&uuml;fen, den Inhalt gegen einen regul&auml;ren Ausdruck und gegen eine frei definierbare PHP-Funktion zu pr&uuml;fen und am Ende den Inhalt noch durch eine PHP-Funktion aufzubereiten.</p>
 
+<p>Die Konfiguration der individuellen Formularfelder geschieht &uuml;ber das PHP-Array <code>$user_fields</code> in <i>config.php</i>. Sie ben&ouml;tigen zun&auml;chst den Namen des Formularfeldes, also das, was Sie im HTML-Formular als Namen angeben. Nehmen wir an, Sie haben folgenden HTML-Code f&uuml;r ein Formularfeld:</p>
+
+<p><code>&lt;input type=&quot;text&quot; name=&quot;beruf&quot; /&gt;</code></p>
+
+<p>Der Name des Feldes lautet also <b>beruf</b>. Dies ben&ouml;tigen wir f&uuml;r die weitere Definition.</p>
+
+<p>Sie k&ouml;nnen nun verschiedene Pr&uuml;fwerte definieren, mit denen <i>Form E-Mail</i> den Inhalt des Formularfeldes &uuml;berpr&uuml;ft und ggf. eine Fehlermeldung ausgibt. Diese werden in der folgenden Tabelle erl&auml;utert (die Tabelle geht der Einfachheit halber weiterhin vom Formularfeld <b>beruf</b> aus - Sie m&uuml;ssen dies nat&uuml;rlich anpassen!):</p>
+
+<table border="1">
+<tr>
+<td><b>Einstellung</b></td>
+<td><b>Beschreibung</b></td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['min']</code></td>
+<td>Geben Sie hier an, wie lang der vom Benutzer eingebene Wert mindestens sein muss</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['max']</code></td>
+<td>Geben Sie hier an, wie lang der vom Benutzer eingebene Wert h&ouml;chstens sein darf</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['required']</code></td>
+<td>Geben Sie hier den Wert 1 an, wenn das Formularfeld ausgef&uuml;llt sein muss. Wenn Sie hier eine 0 oder die Option weglassen, ist das Feld optional.</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['regex']</code></td>
+<td>Geben Sie hier einen <a href="http://de.php.net/manual/de/book.pcre.php">Perl-kompatiblen regul&auml;ren Ausdruck</a> zur Pr&uuml;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>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['check']</code></td>
+<td>Geben Sie hier eine selbst definierte PHP-Funktion (als Zeichenkette) an, durch die der Wert gepr&uuml;ft werden soll. Das erste und einzige Argument der Funktion ist der Inhalt des Formularfeldes. Die Funktion muss <code>true</code> zur&uuml;ckgeben, wenn der Wert in Ordnung ist, ansonsten <code>false</code>.</td>
+</tr>
+</table>
+
+<p>Weiterhin m&uuml;ssen Sie noch diverse Fehlermeldungen definieren (als Unter-Array). Das Definieren dieser Fehlermeldungen ist Pflicht (Sie m&uuml;ssen jedoch nur die Fehlermeldungen zu den Dingen definieren, die auch wirklich gepr&uuml;ft werden).</p>
+
+<table border="1">
+<tr>
+<td><b>Einstellung</b></td>
+<td><b>Beschreibung</b></td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['errors']['too_short']</code></td>
+<td>Der vom Benutzer eingegebene Wert ist nicht lang genug</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['errors']['too_long']</code></td>
+<td>Der vom Benutzer eingegebene Wert ist zu lang</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['errors']['not_set']</code></td>
+<td>Das Formularfeld ist ein Pflichtfeld und es wurde nicht ausgef&uuml;llt.</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['errors']['match_fail']</code></td>
+<td>Die &Uuml;berpr&uuml;fung des Wertes durch den regul&auml;ren Ausdruck ist fehlgeschlagen.</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['errors']['check_fail']</code></td>
+<td>Die &Uuml;berpr&uuml;fung des Wertes durch die PHP-Funktion ist fehlgeschlagen.</td>
+</tr>
+</table>
+
+<p>Zus&auml;tzlich sind noch die folgenden Einstellungen m&ouml;glich:</p>
+
+<table border="1">
+<tr>
+<td><b>Einstellung</b></td>
+<td><b>Beschreibung</b></td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['prepare']</code></td>
+<td>Geben Sie hier eine selbst definierte PHP-Funktion (als Zeichenkette) an, die den Wert des Formularfeldes nach den Pr&uuml;fungen noch ver&auml;ndern (bspw. kann man hier Funktionen angeben, die alle Buchstaben in Gro&szlig;buchstaben umwandelt). Das erste und einzige Argument der Funktion ist der Inhalt des Formularfeldes. Die Funktion muss den bearbeiteten Wert zur&uuml;ckgeben.</td>
+</tr>
+<tr>
+<td><code>$user_fields['beruf']['tpl_var']</code></td>
+<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&auml;re das dann <code>USER_beruf</code>).</td>
+</tr>
+</table>
+
+<p>Sie m&uuml;ssen die individuellen Formularfelder nun noch in Ihrem Mail-Formular und in den <a href="#templates">Templates</a> erg&auml;nzen.</p>
+
+<p>Es folgt Beispiel-Konfiguration f&uuml;r ein Formularfeld namens <i>beruf</i>:</p>
+
+<pre>
+$user_fields['beruf']['min'] = 5;
+$user_fields['beruf']['max'] = 10;
+$user_fields['beruf']['required'] = 1;
+$user_fields['beruf']['regex'] = '/^[A-Za-z]+$/';
+$user_fields['beruf']['check'] = 'check_beruf';
+$user_fields['beruf']['prepare'] = 'prepare_beruf';
+$user_fields['beruf']['tpl_var'] = 'BERUF';
+
+$user_fields['beruf']['errors']['too_short'] = 'Der Beruf muss mind. 5 Zeichen lang sein!';
+$user_fields['beruf']['errors']['too_long'] = 'Der Beruf darf h&ouml;chstens 10 Zeichen lang sein!';
+$user_fields['beruf']['errors']['not_set'] = 'Sie haben keinen Beruf eingegeben!';
+$user_fields['beruf']['errors']['match_fail'] = 'Der Beruf darf nur aus Buchstaben bestehen!';
+$user_fields['beruf']['errors']['check_fail'] = 'Der Beruf sollte keine &auml;&ouml;&uuml; haben!';
+
+# Beispiel-Check-Funktion
+
+function check_beruf($content) {
+    if(strpos($content,'&auml;') !== false) return false;
+    if(strpos($content,'&ouml;') !== false) return false;
+    if(strpos($content,'&uuml;') !== false) return false;
+    
+    return true;
+}
+
+# Beispiel-Vorbereitungs-Funktion
+
+function prepare_beruf($content) {
+    return strtolower($content);
+}
+</pre>
+
+<p>Das Formularfeld hat die folgenden Eigenschaften:</p>
+
+<ul>
+<li>Der Beruf muss aus mind. 5 Zeichen und max. 10 Zeichen bestehen (<code>min</code> und <code>max</code>)</li>
+<li>Das Formularfeld ist ein Pflichtfeld (<code>required</code>)</li>
+<li>Es sind nur die Buchstaben A-Z (gro&szlig; und klein) erlaubt (<code>regex</code>)</li>
+<li>&Uuml;ber die Pr&uuml;ffunktion <code>check_beruf()</code> wird verhindert, dass &auml;, &ouml; und &uuml; angegeben werden (das wird nat&uuml;rlich auch durch den regul&auml;ren Ausdruck ausgeschlossen, es soll lediglich zur Verdeutlichung dienen)</li>
+<li>Durch die Vorbereitungsfunktion <code>prepare_beruf()</code> werden alle Gro&szlig;buchstaben in Kleinbuchstaben umgewandelt</li>
+<li>In den Templates wird die Variable <code>{BERUF}</code> durch den Inhalt des Formularfeldes ersetzt (<code>tpl_var</code>)</li>
+<li>Die Fehlermeldungen sollten selbsterkl&auml;rend sein</li>
+</ul>
+
 <p class="upanddown"><a href="#top">Nach oben</a></p>
 
 <h2><a name="templates" id="templates">Templates anpassen</a></h2>
@@ -513,6 +667,8 @@ Der eingegebene Mail-Text</li>
 Die formatierte Zeitangabe</li>
 </ul>
 
+Weiterhin k&ouml;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 />
+<br />
 Zus&auml;tzlich k&ouml;nnen Sie hier durch Variablen, die mit <b>ENV_</b> beginnen, Server-Umgebungsvariablen im Text einf&uuml;gen (siehe auch Konfigurationsvariable <code>$allowed_envs</code>.
 </td>
 </tr>
@@ -534,6 +690,8 @@ Der eingegebene Mail-Text</li>
 <li><b>TIME</b><br />
 Die formatierte Zeitangabe</li>
 </ul>
+
+Weiterhin k&ouml;nnen Sie hier die definierten Variablen der <a href="#individuell">individuellen Formularfelder</a> (das, was Sie in <code>tpl_var</code> angegeben haben) verwenden.
 </td>
 </tr>
 <tr>
@@ -553,6 +711,8 @@ Der Betreff der Mail</li>
 Der eingegebene Mail-Text</li>
 </ul>
 
+Weiterhin k&ouml;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 />
+<br />
 Zus&auml;tzlich ist es m&ouml;glich, einen Bereich, der nur angezeigt werden soll, wenn Captchas aktiviert sind, anzuzeigen, indem Sie diesen in folgenden Block einschlie&szlig;en (der <code>{ELSE}</code>-Teil ist optional):<br />
 <br />
 <code>{IF CAPTCHA}Captchas sind aktiviert{ELSE}Captchas sind nicht aktiviert{ENDIF}</code>