NAVIGATION
Table of Contents
PHP function include
Since the release of r282 it is possible to process an own PHP function between the action “submit” and “sending the E-Mail”. This function can read all the form input, modify, and return it. (Also, the transmission destination (email address) may be changed).
These changes are not recorded in the database, because the values were written into the database before the function is called.
The function call must be registered in the form in the fields “php function:” below “recipient template:“ or “copy to - template:“. (See picture below).
The function itself is stored in a file in folder “template/inc_script/frontend_init/” .
function my_form_title_recipient_de( &$postvar, &$form, &$mail ) { .... } function my_form_title_copy_to_de( &$postvar, &$form, &$mail ) { .... }
Docu: –
Forum: –
Author: K.Heermann (flip-flop) (22.01.10)
CMS-Version: >= V1.4.1 r282
Version: V1.0 22.01.10
Condition: → /config/phpwcms/conf.inc.php
- $phpwcms['allow_ext_init'] = 1;
Example exercise:
The e-mails to the user (To) and the site operators (CC) is to be given a correct address, which is controlled by the address selection
[Frau] - [Herr] - [Firma] ([Mrs] - [Mr] - [company])
In german language we have difficult titles like “Sehr geehrte Frau” - “Sehr geehrter Herr” instead of your Dear Ms / Miss / Mrs / Mr:
[Frau] "Sehr geehrte Frau ...." [Herr] "Sehr geehrter Herr ...." [Firma] "Sehr geehrte Damen und Herren"
In addition, the dispatched e-mail will be displayed again after the “send” (submit).
- BE: In the templates for To “recipient - template” and CC “copy to - template” a placeholder [%TITLE%] is used for the address.
- Script: Replace the placeholder [%TITLE%] in both e-mail text by the corresponding address
- FE: Output of the email text (To) on the following page after sending
Frontend-Input
The simple form
Frontend-Output
The corrected e-mail will be presented and delivered.
Backend
The simple form in backend.
Specificities:
The field “on success:“ must be labeled as HTML, because this field will be used for the display of the sent e-mail. (Is filled by the script).
Please pay attention to the placeholder [%TITLE%] in the templates and the entries
- my_form_title_recipient_de below “recipient template” and
- my_form_title_copy_to_de below “copy to - template”
in “php function:“.
Backend-Code
Recipient template: / copy to - template:
… are coincidentally identical.
Name: {title} {name}
E-Mail: {email}
Nachricht:
------------------------------
{notice}
------------------------------
[%TITLE%],
wir bedanken uns für das Interesse und werden uns in Kürze bei Ihnen melden.
Mit freundlichem Gruß
Sir-Oblong-Fitz-Oblong
The templates can also be generated as HTML. The output after sending works correctly.
Template:
<div style="width:510px; padding:10px; margin:10px; border:1px dotted #666; background: #E2DFFF;"> <span style="color:red">[B]{ERROR:title}[/B]</span> [B]{LABEL:title}[/B][BR]{title}[BR][BR] <span style="color:red">[B]{ERROR:name}[/B]</span> [B]{LABEL:name}[/B][BR]{name}[BR][BR] <span style="color:red">[B]{ERROR:email}[/B]</span> [B]{LABEL:email}[/B][BR]{email}[BR][BR] <span style="color:red">[B]{ERROR:notice}[/B]</span> [B]{LABEL:notice}[/B][BR]{notice}[BR][BR] <span style="color:red">[B]{ERROR:nospam}[/B]</span> [B]{LABEL:nospam}[/B][BR]{nospam}[BR][BR] {submitIt} </div>
Digression Functions / Variables
First the function for “recipient - template (” my_form_title_recipient_de ”) and in a second call the function for “copy to - template ( “my_form_title_copy_to_de”) is processed. At this time we cannot control the order.
A function call will be autom. pass the three arrays $postvars, $form and $mail (see below).
Example:
The function call from the form with “my_incredible_function” is expecting the function
function my_incredible_function( &$postvar, &$form, &$mail ) { .... }
in a file within the folder template/inc_script/frontend_init/
All parameters can be read and processed. Interesting are the two values in $form['template'] and $form['template_copy'].
In these two variables we find the generated email text from “recipient - template” (“my_form_title_recipient_de”) and “copy to - template” (“my_form_title_copy_to_de”).
These texts can be read, manipulated and written back now by php.
After processing of the functions the emails are sent to the registered addresses.
The database is already filled before calling the function, here the manipulated result is not recorded.
Test script:
File: template/inc_script/frontend_init/form_test.php
Condition: $phpwcms['allow_ext_init'] = 1; → /config/phpwcms/conf.inc.php
<?php /********************************************************************************************/ /** * Script for the function of the form * * 17.03.2010 (c) K.Heermann http://planmatrix.de */ /********************************************************************************************/ // ------------------------------------------------------------------------------------------- // obligate check for phpwcms constants if (!defined('PHPWCMS_ROOT')) {die("You Cannot Access This Script Directly, Have a Nice Day."); } // ------------------------------------------------------------------------------------------- /** For testing form function =============================================================================== =============================================================================== */ function form_test( &$postvar, &$form, &$mail ) { echo '<br>===== postvar ===========================<br>'; dumpVar($postvar); echo '<br>===== form ==============================<br>'; dumpVar($form); echo '<br>===== mail ==============================<br>'; // Security risk if you forgot to remove the script after finishing work. // Is also unattractive for most applications. // dumpVar($mail); echo '<br>===== mail ende =========================<br>'; } // ==== End function /* =============================================================================== =============================================================================== */ ?>
Content: $postvar
Contents of the array $postvar using
dumpVar($postvar);
<note>
$postvar is spent only if [X] save form results is turned on, because you see the already stored data from the DB.
A change in this data is not possible (has no effect on the DB or the dispatch results).
</note>
function my_form_id( &$postvar, &$form, &$mail ) { dumpVar($postvar); }
Array ( [title] => Herr [name] => Franz Mustermann [email] => f-mustermann@example.com [notice] => Bitte geben Sie hier Ihre Nachricht ein [nospam] => 12 )
Content: $form
Content of the arrays $form using
dumpVar($form);
function my_form_id( &$postvar, &$form, &$mail ) { dumpVar($form); }
Array ( [subject] => Vom Kontaktformular example.com [startup] => [B]E-Mail versenden![/B][BR] [startup_html] => 0 [class] => [error_class] => error [label_wrap] => Array ( [0] => [1] => ) [cform_reqmark] => * [cc] => Array ( [0] => formular@example.com ) [targettype] => emailfield_email [target] => Array ( [0] => f-mustermann@example.com ) [subjectselect] => [sendertype] => system [sender] => kontakt@example.com [sendernametype] => custom [sendername] => [verifyemail] => [labelpos] => 2 [sendcopy] => 1 [copyto] => Franz Mustermann [formtracking_off] => 1 [checktofrom] => 0 [onsuccess_redirect] => 2 [onerror_redirect] => 2 [onsuccess] => [B]Die E-Mail wurde erfolgreich gesendet![/B][BR]<div style="width:510px; padding:10px; margin:10px; border:1px dotted #666; background:#eee;">Name: Herr Franz Mustermann <br /> <br /> E-Mail: f-mustermann@example.com <br /> <br /> Nachricht: <br /> ------------------------------ <br /> Bitte geben Sie hier Ihre Nachricht ein <br /> ------------------------------<br /> <br /> <br /> Sehr geehrter Herr Franz Mustermann, <br /> <br /> wir bedanken uns für das Interesse und werden uns in Kürze bei Ihnen melden. <br /> <br /> <br /> Mit freundlichem Gruß<br /> <br /> Sir-Oblong-Fitz-Oblong</div><div style="padding:20px 0 0 20px; font-weight:bold;"><a href="category04_01_05.phtml"> >>Weiter >></a></div> [onerror] => <span style="color:red">[B]Bitte achten Sie auf den unten angezeigten Fehler![/B]</span> [template_format] => 0 [template] => Name: Herr Franz Mustermann E-Mail: f-mustermann@example.com Nachricht: ------------------------------ Bitte geben Sie hier Ihre Nachricht ein ------------------------------ Sehr geehrter Herr Franz Mustermann, wir bedanken uns für das Interesse und werden uns in Kürze bei Ihnen melden. Mit freundlichem Gruß Sir-Oblong-Fitz-Oblong [template_format_copy] => 0 [template_copy] => Name: Herr Franz Mustermann E-Mail: f-mustermann@example.com Nachricht: ------------------------------ Bitte geben Sie hier Ihre Nachricht ein ------------------------------ Sehr geehrter Herr Franz Mustermann, wir bedanken uns für das Interesse und werden uns in Kürze bei Ihnen melden. Mit freundlichem Gruß Sir-Oblong-Fitz-Oblong [function_to] => my_form_title_recipient_de [function_cc] => my_form_title_copy_to_de [template_equal] => 0 [customform] => <div style="width:510px; padding:10px; margin:10px; border:1px dotted #666; background: #E2DFFF;"> <span style="color:red">[B]{ERROR:title}[/B]</span> [B]{LABEL:title}[/B][BR]{title}[BR][BR] <span style="color:red">[B]{ERROR:name}[/B]</span> [B]{LABEL:name}[/B][BR]{name}[BR][BR] <span style="color:red">[B]{ERROR:email}[/B]</span> [B]{LABEL:email}[/B][BR]{email}[BR][BR] <span style="color:red">[B]{ERROR:notice}[/B]</span> [B]{LABEL:notice}[/B][BR]{notice}[BR][BR] <span style="color:red">[B]{ERROR:nospam}[/B]</span> [B]{LABEL:nospam}[/B][BR]{nospam}[BR][BR] {submitIt} </div> [savedb] => 1 [saveprofile] => 0 [fields] => Array ( [1] => Array ( [type] => select [name] => title [label] => Anrede [required] => 0 [value] => Frau Herr Firma [error] => Fehler:- [style] => [class] => [profile] => [size] => [max] => ) [2] => Array ( [type] => text [name] => name [label] => Name [required] => 1 [value] => Franz Mustermann [error] => Fehler:- [style] => [class] => [profile] => [size] => 48 [max] => ) [3] => Array ( [type] => email [name] => email [label] => eMail [required] => 1 [value] => f-mustermann@example.com [error] => Fehler:- [style] => [class] => [profile] => [size] => 48 [max] => ) [4] => Array ( [type] => textarea [name] => notice [label] => Nachricht [required] => 0 [value] => Bitte geben Sie hier Ihre Nachricht ein [error] => Fehler:- [style] => [class] => [profile] => [size] => 37 [max] => 3 ) [5] => Array ( [type] => mathspam [name] => nospam [label] => Spamschutz [required] => 1 [value] => Array ( [+] => Summieren [-] => Subtrahieren [*] => Multiplizieren [:] => Dividieren [calc] => Berechnung: ) [error] => Fehler:- [style] => [class] => [profile] => [size] => 10 [max] => ) [6] => Array ( [type] => submit [name] => submitIt [label] => Senden [required] => 0 [value] => Senden [error] => Fehler:- [style] => [class] => [profile] => [size] => [max] => ) ) [is_enctype] => [regx_pattern] => Array ( [A-Z] => /^[A-Z]+$/ [a-Z] => /^[a-zA-Z]+$/ [a-z] => /^[a-z]+$/ [0-9] => /^[0-9]+$/ [PHONE] => /^[+]?([0-9]*[\.\s\-\(\)\/]|[0-9]+){3,24}$/ [INT] => /^[0-9\-\+]+$/ [WORD] => /^[\w]+$/ [LETTER+SPACE] => /^[a-z _\-\:]+$/i ) [is_html_entity] => [fe_current_url] => http://example.com/index.php?category04_01_05 )
$form['template'] and $form['template_copy']
Of interest are the two ranges $form['template'] and $form['template_copy'], they are containing the processed email text.
Both texts are identical, for simplicity, but could also be different.
- $form['template'] ⇒ Text “to” so from “recipient - template”
- $form['template_copy'] ⇒ Text “CC” so from “copy to - template”
Name: Herr Franz Mustermann E-Mail: f-mustermann@example.com Nachricht: ------------------------------ Bitte geben Sie hier Ihre Nachricht ein ------------------------------ Sehr geehrter Herr Franz Mustermann, wir bedanken uns für das Interesse und werden uns in Kürze bei Ihnen melden. Mit freundlichem Gruß Sir-Oblong-Fitz-Oblong
The correct personal address was substituted with the help of the script by the placeholder [%TITLE%] in the emails To and CC.
This text is now correctly sent as email.
Core: php function
File: template/inc_script/frontend_init/my_form_title_de.php
The correct personal address is spent in the e-mails To and CC.
<?php // ------------------------------------------------------------------------------------------- // obligate check for phpwcms constants if (!defined('PHPWCMS_ROOT')) {die("You Cannot Access This Script Directly, Have a Nice Day."); } // ------------------------------------------------------------------------------------------- /********************************************************************************************* Simple script for calling a PHP function from a form, after the submit The correct personal address is spent in the e-mails To and CC The e-mail text is displayed after a successful send Einfaches Script fur den Aufruf einer PHP-Funktion aus einem Formular heraus nach dem submit. Die richtige Anrede personenbezogen wird in den E-Mails To und CC ausgegeben Der E-Mailtext wird nach erfolgreichem senden ausgegeben 20.01.2009 K.Heermann http://planmatrix.de **********************************************************************************************/ /* ----------------------------------------------------- [Frau] Sehr geehrte Frau XXX [Herr] Sehr geehrter Herr XXX [Firma] Sehr geehrte Damen und Herren der Firma XXX ---------------------------------------------------------*/ // Function using in recipient template // Funktion fuer das "Empfaenger"-Template function my_form_title_recipient_de( &$postvar, &$form, &$mail ) { // Die richtige Anrede suchen // Set up the right title // --------------------------------------------------------------- $result = ''; switch (trim($postvar['title'])) { case 'Frau': $result = 'Sehr geehrte Frau '.trim($postvar['name']); break; case 'Herr': $result = 'Sehr geehrter Herr '.trim($postvar['name']); break; case 'Firma': $result = 'Sehr geehrte Damen und Herren'; break; default: $result = 'Sehr geehrte Damen und Herren'; } // Replace the form placeholder [%TITLE%] in both e-mail texts by the right title // Ersetzen des Formularplatzhalters [%TITLE%] in beiden E-Mailtexten durch die richtige Anrede // --------------------------------------------------------------- $form['template'] = str_replace('[%TITLE%]',$result, $form['template']); // recipient: / Empfaenger: // Output e-mail text // Ausgabe E-Mailtext // --------------------------------------------------------------- $email_text = '<div style="width:510px; padding:10px; margin:10px; border:1px dotted #666; background:#eee;">'; $email_text .= $form['template']; $email_text .= '</div>'; // More link // Weiter link $email_text .= '<div style="padding:20px 0 0 20px; font-weight:bold;">'; $email_text .= '<a href="'.$GLOBALS['content']["struct"][$GLOBALS['content']["cat_id"]]["acat_alias"].'.phtml">'; $email_text .=' >>Weiter >></a>'; $email_text .= '</div>'; // Insert e-mail text and if non HTML: convert LF to <br> // Einsetzen des E-Mailtextes und wenn kein HTML LF nach <br> $form['onsuccess'] .= ($form['template_format'] == 1) ? $email_text : nl2br($email_text); } // ==== End function // Function using in copy to template // Funktion fuer das "Kopie an" Template function my_form_title_copy_to_de( &$postvar, &$form, &$mail ) { // Die richtige Anrede suchen // Set up the right title // --------------------------------------------------------------- $result = ''; switch (trim($postvar['title'])) { case 'Frau': $result = 'Sehr geehrte Frau '.trim($postvar['name']); break; case 'Herr': $result = 'Sehr geehrter Herr '.trim($postvar['name']); break; case 'Firma': $result = 'Sehr geehrte Damen und Herren'; break; default: $result = 'Sehr geehrte Damen und Herren'; } // Replace the form placeholder [%TITLE%] in both e-mail texts by the right title // Ersetzen des Formularplatzhalters [%TITLE%] in beiden E-Mailtexten durch die richtige Anrede // --------------------------------------------------------------- $form['template_copy'] = str_replace('[%TITLE%]',$result, $form['template_copy']); // copy to: / Kopie an: } // ==== End function ?>
Output of the email text (To) on the following page after sending
The BE field “on success:” is filled in the script with the e-mail text from To (recipient - template) of the variable $form['template'].
To do this we write the text, wrapped into a little formatting, from $form['template'] into the variable $form['onsuccess'].
Moreover, is still a link (more) generated at current page (form).
Use of the i18n @@Replacementtags@@ in e-mails, for multilingual sides
The process described above can be very simply used to translate e-mail text using the i18n function Internationalisation (i18n) of phpwcms.
Assuming we'll write the following e-mail template:
@@Company@@: {company}
@@Subject@@: {subject}
and want to have @@Company@@ for German e-mail recipient (e.g. for the email copy) as “Firma” and/or @@Subject@@ as “Betreff” in the e-mail stands for.
Then the following simple function helps:
function email_i18n_substitute_text(&$postvar, &$form, &$mail){ $form['template'] = i18n_substitute_text($form['template']); $form['template_copy'] = i18n_substitute_text($form['template_copy']); }
email_i18n_substitute_text must be registered as function in backend/form cp as described above.
Naturally also the appropriate language file must be translated additionally.
