315 lines
12 KiB
Markdown
315 lines
12 KiB
Markdown
# gamuMail
|
|
> formulaire d'envoi de messages configurables
|
|
## Il gere nativement :
|
|
* Pour
|
|
* Cc en meta : **gamumail/mail_cc**
|
|
* Cci en en meta : **gamumail/mail_cci**
|
|
* Sujet
|
|
* Texte
|
|
* Les documents attachés au modèle (cf ci-dessous)
|
|
* une liste de pdf (il faut le plugin spipdf)
|
|
|
|
|
|
## Il gere des modèles de contenu pour :
|
|
* Sujet
|
|
* Texte
|
|
* ID documents joints (spip_documents)
|
|
---
|
|
* Chaque modèle à un identifiant textuel : **slug** qui doit etre unique. Il ne peut etre créé / modifié QUE par les webmestres
|
|
* Pour gerer ses modèles, il faut se rendre sur la page : `?page=configuration_mails`
|
|
|
|
|
|
## Personnalisation du formulaire d'envoi
|
|
### Dans le html
|
|
On peut ajouter des documents via un fichier du type : **gamumail/SLUG_fichier.html** SLUG doit etre remplacé par le nom du slug du modèle
|
|
> **/!\ Le name doit etre Tid_doc**
|
|
>
|
|
ex de fichier :
|
|
```html
|
|
<B_doc>
|
|
<h2>Fichiers attachés au séjour</h2>
|
|
<div class="editer_groupe">
|
|
<div class="editer editer_[(Tid_doc)]">
|
|
<BOUCLE_doc(DOCUMENTS){id_article=#ENV{options/id_article}}{extension=pdf}>
|
|
<div class="choix">
|
|
<input type="checkbox" class="checkbox" name="Tid_doc[]" value="#ID_DOCUMENT" id="Tid_doc_#ID_DOCUMENT" checked="checked" >
|
|
<label for="Tid_doc_#ID_DOCUMENT">
|
|
<i class="fa fa-file-pdf-o rouge"></i>[ (#TITRE|sinon{#FICHIER|basename})] :
|
|
<a class="mediabox" href="#URL_DOCUMENT">voir le fichier</a>
|
|
</label>
|
|
</div>
|
|
</BOUCLE_doc>
|
|
</div>
|
|
</div>
|
|
</B_doc>
|
|
```
|
|
3 branchements possibles :
|
|
* gamumail/SLUG_debutform.html -> au début du form
|
|
* gamumail/SLUG_soustexte.html -> sous le contenu du mail, avant les pièces jointes
|
|
* gamumail/SLUG_fichier.html -> à la fin du formulaire
|
|
|
|
### aide à la rédaction du contenu:
|
|
- le fichier **gamumail/remplacement_slugs.html** s'affiche en bas de la page de configuration des modèles **inclure/gamumail_config.html**
|
|
et du formulaire d'envoi **formulaires/gamumail.html** : il permet de lister les remplacements effectués pour **tous les modèles** qui sont :
|
|
- les génériques fournis par Gamumail par la fonction `inc_gamumail_remplacements_dist()` du fichier `inc/gamumail_remplacements.php`
|
|
- ceux fournis par les plugins via le pipeline **remplacement_slugs** (cf ci-dessous)
|
|
- pour documenter les remplacements (pied de la page gamumail_config.html), chaque plugin doit renseigner ses remplacements dans l'array global `$GLOBALS['remplacements_gamumail']`
|
|
Exemple dans un fichier `prefixe_fonctions.php` :
|
|
```php
|
|
$GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture';
|
|
```
|
|
- une page de test des slugs est fournie à l'URL **...?page=test_slug&slug=mail_libre&dest=27**
|
|
|
|
### exemple de page d'envoi de mail en choisissant un slug parmi ceux existant :
|
|
```html
|
|
[(#AUTORISER{modifier,souscripteur,#ENV{id_auteur}}|sinon_interdire_acces)]
|
|
|
|
<BOUCLE_dest(AUTEURS){id_auteur=#ENV{dest}}{tout}>
|
|
<div class="inner">
|
|
<div class="ajax mbl">
|
|
<h1>Envoyer un mail à [(#PRENOM|ucfirst) ][(#NOM|ucfirst)]</h1>
|
|
|
|
<INCLURE{fond=inclure/envoyer_gamumail, env, id_destinataire=#ID_AUTEUR}>
|
|
</div>
|
|
</div>
|
|
</BOUCLE_dest>
|
|
```
|
|
|
|
### Dans le php
|
|
#### 1. Appel du formulaire
|
|
> Args du formulaire :
|
|
>
|
|
```php
|
|
/**
|
|
* formulaire générique pour envoyer des mails avec pieces attachés
|
|
*
|
|
* @param string $slug modele du mail a charger
|
|
* @param string $destinataires = adresses mails et id_auteurs séparées par , ou en array
|
|
* si un des destinataire est au format numérique, on considère que c'est un id_auteur et on va choper son mail dans spip_auteurs
|
|
* @param array $Tclient = un ou plusieurs mails de destinataires sortis d'une table objet spécifique
|
|
* de la forme []['objet' => 'app_client', 'id_objet' => 3, 'champ' => 'email'] ou ['objet' => 'app_client', 'id_objet' => 3, 'champ' => 'email']
|
|
* @param array $Tpdf = un ou plusieurs fichiers PDF générés par spiPDF (le contexte permet la personnalisation du contenu)
|
|
* []['fichier' => 'pdf_facture', 'nom' => 'facture_123', 'contexte' => ['id_app_facture' => 3]] ou ['fichier' => 'pdf_facture', 'nom' => 'facture_123', 'contexte' => ['id_app_facture' => 3]]
|
|
* @param string $redirect
|
|
* @param array $options = un gros fourre-tout sous forme d'un array
|
|
* utilisé en particulier par les inclure HTML de gamumail/#SLUG_soustexte et gamumail/#SLUG_fichiers
|
|
*
|
|
* @return array $valeurs
|
|
*/
|
|
function formulaires_gamumail_charger_dist($slug, $auteur = 0, $Tclient = [], $Tpdf = [], $redirect = '', $options = []){
|
|
}
|
|
```
|
|
#### argument $slug "no_gamumail"
|
|
Si $slug à pour valeur **no_gamumail** alors l'envoi est annulé
|
|
Exemple d'option à insérer dans un select sélecteur de slug :
|
|
```html
|
|
<option value="no_gamumail"[ (#ENV{slug}|=={no_gamumail}|oui) selected="selected"]><:souscriptions:pas_de_mail_auto:></option>
|
|
```
|
|
|
|
#### argument Tclient
|
|
l'Argument $Tclient est utilisé pour récupérer des emails dans un ou X autres Objets SPIP
|
|
|
|
#### argument Tpdf : attacher des PDF avec contenu dynamique
|
|
- exemple d'appel pour 1 fichier PDF avec son contexte :
|
|
```html
|
|
[(#FORMULAIRE_GAMUMAIL{
|
|
#ENV{slug},
|
|
#ENV{email},
|
|
'',
|
|
#ARRAY{
|
|
fichier,pdf_guide,
|
|
nom,Fiche_guide,
|
|
contexte,#ARRAY{
|
|
id_article,#ENV{id_article},
|
|
type_guide,#ENV{type_guide,guide}
|
|
}
|
|
},
|
|
#ENV{redirect},
|
|
#ARRAY{
|
|
id_auteur,#ENV{id_auteur}
|
|
}
|
|
})]
|
|
```
|
|
le fichier PDF sera généré par SPIPDF avec l'URL suivante : `...spip.php?page=spipdf&spipdf=pdf_guide&id_article=1838&type_guide=guide`
|
|
|
|
- exemple d'appel pour 2 fichiers PDF générés par le même squelette (pdf_guide.html) mais avec chacun leur contexte :
|
|
```html
|
|
[(#FORMULAIRE_GAMUMAIL{
|
|
#ENV{slug},
|
|
#ENV{email},
|
|
'',
|
|
#ARRAY{
|
|
0,#ARRAY{
|
|
fichier,pdf_guide,
|
|
nom,Fiche_guide,
|
|
contexte,#ARRAY{
|
|
id_article,#ENV{id_article},
|
|
type_guide,guide,
|
|
}
|
|
},
|
|
1,#ARRAY{
|
|
fichier,pdf_guide,
|
|
nom,Fiche_guide_renfort,
|
|
contexte,#ARRAY{
|
|
id_article,#ENV{id_article},
|
|
type_guide,guide_renfort,
|
|
}
|
|
}
|
|
},
|
|
#ENV{redirect},
|
|
#ARRAY{
|
|
id_auteur,#ENV{id_auteur}
|
|
}
|
|
})]
|
|
```
|
|
/!\ en cas de plusieurs PDF :
|
|
- il faut une *clé unique* pour chaque #ARRAY (0, 1, 2... est une bonne solution)
|
|
- dans l'#ARRAY contexte il faut que le dernier élément soit suivi d'une virgule ou d'une accolade fermante
|
|
|
|
#### 2. modification de chaque étape: charger / vérifier / traiter
|
|
Pour chaque étape, on peut modifier l'Array de sortie :
|
|
* charger -> $valeurs
|
|
* verifier -> $erreurs
|
|
* traiter -> $corps (array du message envoyé à facteur)
|
|
|
|
Voir **gamumail_fonctions.php** pour les arguments des fonctions de surcharge + exemples
|
|
|
|
Pour cela, il faut creer une fonction du type (qui utilise les memes arg que les fonctions CVT + premier arg l'Array que l'on veut modifier):
|
|
* pour charger : **gamumail/charger.php** pour tous les formulaires ou
|
|
* pour charger : **gamumail/SLUG_charger.php** avec une fonction :
|
|
```php
|
|
function gamumail_SLUG_charger($valeurs, $options = []){
|
|
return $valeurs;
|
|
}
|
|
```
|
|
* pour verifier : **gamumail/verifier.php** pour tous les formulaires ou
|
|
* pour verifier : **gamumail/SLUG_verifier.php** avec une fonction :
|
|
```php
|
|
function gamumail_SLUG_verifier($erreurs, $options = []){
|
|
return $erreurs;
|
|
}
|
|
```
|
|
* pour traiter : **gamumail/SLUG_traiter.php** avec une fonction ex:
|
|
```php
|
|
function gamumail_contrat_resa_traiter($corps, $options = []){
|
|
if (array_key_exists('id_article', $options)) {
|
|
$htmlAdd = '';
|
|
$texteAdd = '';
|
|
$id_article = intval($options['id_article']);
|
|
$htmlAdd = recuperer_fond('gamumail/traiter_contrat_resa', ['id_article' => $id_article]);
|
|
if (!empty($htmlAdd)) {
|
|
include_spip('classes/facteur');
|
|
|
|
$html = $corps['html'];
|
|
$html = str_replace('@@pieces_jointes@@', $htmlAdd, $html);
|
|
$texte = facteur_mail_html2text($html);
|
|
$corps['html'] = $html;
|
|
$corps['texte'] = $texte;
|
|
}
|
|
}
|
|
|
|
return $corps;
|
|
}
|
|
```
|
|
#### 3. Pipeline remplacements_slug pour le traitement du contenu des messages
|
|
Pour les remplacements des @@ et tout autre traitement du texte des mails on utilisera le pipeline **remplacements_slug** qui utilise les arguments suivants :
|
|
```php
|
|
* @param array $flux données du pipeline :
|
|
* $flux['data'] = $html
|
|
* $flux['args']['slug'] = $slug
|
|
* $flux['args']['destinataires'] = $destinataires
|
|
* $flux['args']['options'] = $options
|
|
* @return array $flux données du pipeline
|
|
function PREFIX_remplacements_slug($flux){
|
|
include_spip('gamumail_fonctions');
|
|
|
|
// remplacements statiques
|
|
if ($html = $flux['data']) {
|
|
$html = gamumail_remplacer_modele('url_page_commandes', url_absolue(generer_url_public('historique_commandes')), $html);
|
|
$html = gamumail_remplacer_modele('url_page_contrats', url_absolue(generer_url_public('mes_contrats')), $html);
|
|
}
|
|
|
|
// remplacements dynamiques
|
|
/*
|
|
* /!\ Attention, $flux['args'] peut etre un array cle -> valeur
|
|
* sans passer par un sous tab $args comme ici
|
|
*/
|
|
if ($args = $flux['args']['args']
|
|
and $html = $flux['data']
|
|
) {
|
|
if (isset($args['url_attestation'])) {
|
|
$html = gamumail_remplacer_modele('url_attestation', $args['url_attestation'], $html);
|
|
}
|
|
$flux['data'] = $html;
|
|
}
|
|
|
|
return $flux;
|
|
}
|
|
|
|
```
|
|
#### 4. Pipeline post_gamumail_ok
|
|
Ce pipeline est appelé si le retour de l'envoi du gamumail est OK. Il permet, par exemple, à Paybyurl d'aller modifier le champ date_paybyurl_envoye pour que la date d'envoi soit mise à jour.
|
|
|
|
#### 5. Ajouter un header / footer dans le content html
|
|
on peut définir un header / footer pour les messages :
|
|
* gamumail/html_header.html => header pour tous les mails
|
|
* gamumail/html_footer.html => footer pour tous les mails
|
|
* gamumail/SLUG_html_header.html => pour les mails du modele SLUG
|
|
* gamumail/SLUG_html_footer.html => pour les mails du modele SLUG
|
|
|
|
#### 6. Utiliser l'inclure `<INCLURE{fond=inclure/fermer_modale,env}>` pour fermeture de la modale de gamumail
|
|
- cet inclure est appelé au début de `formulaire/gamumail.html` : par défaut il est vide
|
|
- un plugin peut arriver avec son fichier pour le surcharger afin de pouvoir intégrer du JS en fonction du message de retour `message_ok` du traiter de gamumail.php
|
|
- dans `gamumail.php`, la fonction `gamumail_traiter` ajoute en fin du message de retour OK `message_ok` le suffixe `@@gamumail_ok`
|
|
- il est donc possible de tester la présence de ce suffixe dans `message_ok` pour afficher du JS qui permet de refermer la modale dans laquelle est chargée gamumail
|
|
mais aussi de faire la mise à jour de l'affichage d'un bloc ajax dans la page appelante.
|
|
=> voir le code en commentaire dans le fichier `inclure/fermer_modale`
|
|
|
|
## API d'envoi de mails utilisant les slugs
|
|
### fonction envoyer_gamumail()
|
|
- exemple d'appel :
|
|
```php
|
|
$fonction = charger_fonction('envoyer_gamumail','inc');
|
|
$options = [
|
|
'debug' => false,
|
|
'options' => ['nb_parts' => intval(_request('nombre'))],
|
|
'pdfs' => [
|
|
[
|
|
'fichier' => 'pdf_attestation_souscription',
|
|
'nom' => 'attestation_souscription_'.$id_souscription,
|
|
'contexte' => ['id_souscription' => $id_souscription]
|
|
],
|
|
],
|
|
];
|
|
$fonction(lire_config('souscriptions/slug_souscription_validation'), $Tdest, $options);
|
|
```
|
|
- arguments :
|
|
```php
|
|
* @param string $slug
|
|
* @param string|array $destinataires = adresses mails et id_auteur séparées par , ou en array
|
|
* si un des destinataire est au format numérique, on considère que c'est un id_auteur et on va choper son mail dans spip_auteurs
|
|
* @param array $options :
|
|
* $options['debug' => true] pour afficher le $corps final sans envoyer le mail
|
|
* $options['cci' => true] pour passer tous les destinataires en cci si il y en a plus qu'un
|
|
* $options['args' => ['param_1' => 'valeur_1, 'param_2' => 'valeur_2', ...]]
|
|
* $options['pdfs' => [...]] array des fichiers PDF générés à attacher dont les éléments peuvent être :
|
|
* - soit un nom de squelette PDF
|
|
* - soit un array avec 3 éléments (seul le 1er est obligatoire):
|
|
* [ 'fichier' => 'squelette_PDF',
|
|
* 'contexte' => ['parametre_url_1' => 'valeur_1', 'parametre_url_2' => 'valeur_2', ...]
|
|
* 'nom' => 'nom_fichier_attache' ]
|
|
```
|
|
|
|
## Outrepasser l'erreur de certificat auto-signé lors de devs en https local
|
|
=> dans le mes_options.php du site mettre :
|
|
```
|
|
define('_DEBUG_AUTORISER', true);
|
|
```
|
|
ce qui permet d'activer les options de curl pour ne pas vérifier le certificat dans *charger_pdf.php* :
|
|
```
|
|
// pour une connexion https locale avec certificat auto-signé
|
|
if (defined('_DEBUG_AUTORISER')) {
|
|
curl_setopt($CurlConnect, CURLOPT_SSL_VERIFYHOST, false);
|
|
curl_setopt($CurlConnect, CURLOPT_SSL_VERIFYPEER, false);
|
|
}
|
|
```
|