{{indexmenu_n>150}}

====== 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/" .

<code php>
function my_form_title_recipient_de( &$postvar, &$form, &$mail ) { .... }

function my_form_title_copy_to_de( &$postvar, &$form, &$mail ) { .... }
</code>

\\
----
----

Docu: -- \\
Forum: --

**Author:** [[http://planmatrix.de|K.Heermann]] //(flip-flop) (22.01.10)// \\
**CMS-Version:** >= V1.4.1 r282 \\
**Version:** V1.0  //22.01.10// \\


**Condition:**  -> [[http://www.phpwcms-docu.de/conf_inc_php_en.phtml|/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 geehrte##r## //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

{{:deutsch:phpwcms-system:artikel:contentparts:formular:spezielle-anwendungen:php_function_include_fe01_de_1.gif|}}

\\

===== Frontend-Output =====

The corrected e-mail will be presented and delivered. 


{{:deutsch:phpwcms-system:artikel:contentparts:formular:spezielle-anwendungen:php_function_include_fe02_de_1.gif|}}

~~UP~~


===== 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:"**.

\\
{{:deutsch:phpwcms-system:artikel:contentparts:formular:spezielle-anwendungen:php_function_include_be01_de_1.gif|}}


~~UP~~


===== Backend-Code =====

==== Recipient template: / copy to  - template:  ====

... are coincidentally identical.

<code>
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
</code>

\\
The templates can also be generated as HTML. The output after sending works correctly.

\\

==== Template: ====

<code php>
<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>
</code>

~~UP~~




===== 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; -> [[http://www.phpwcms-docu.de/conf_inc_php_en.phtml|/config/phpwcms/conf.inc.php]] \\

<code php|h form_test.php |h>
<?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 
/*
===============================================================================
===============================================================================
*/

?>
</code>

\\

----

\\

 

==== Content: $postvar ====

Contents of the array $postvar using 
<code php>dumpVar($postvar);</code>




<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>

<code php>function my_form_id( &$postvar, &$form, &$mail ) { dumpVar($postvar); } </code>

<code php|h Ausgabe $postvar |h>
Array
(
    [title] => Herr
    [name] => Franz Mustermann
    [email] => f-mustermann@example.com
    [notice] => Bitte geben Sie hier Ihre Nachricht ein
    [nospam] => 12
)

</code>

\\

==== Content: $form ====

Content of the arrays $form using 
<code php>dumpVar($form);</code>

<code php>function my_form_id( &$postvar, &$form, &$mail ) { dumpVar($form); } </code>

<code php|h Ausgabe $form |h>
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
)

</code>

\\

=== $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"**

\\
<file>
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 
</file>

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.

<code php|h my_form_title_de.php |h>
<?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 

?>
</code>

\\


===== 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 [[english/phpwcms_replacer_rts/integrated-tags/language-tags/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:

<code php>
function email_i18n_substitute_text(&$postvar, &$form, &$mail){	
	$form['template'] = i18n_substitute_text($form['template']);
	$form['template_copy'] = i18n_substitute_text($form['template_copy']);	
}
</code>

\\

**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.
\\
\\