PHP function include
Use of the i18n @@Replacementtags@@ in e-mails, for multilingual sides

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

form_test.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); }

Ausgabe $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); }

Ausgabe $form

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

my_form_title_de.php

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