SPIP/gamuMail
SPIP/gamuMail
4
0
Fork 0
Code Issues 2 Pull requests Projects Releases Wiki Activity

doc

Browse source
This commit is contained in:
Christophe 2025-01-02 14:12:18 +01:00
parent 27d04e9eee
commit ee44ab4bed
1 changed files with 114 additions and 87 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

201
README.md
View file

@ -1,30 +1,41 @@
# gamuMail # gamuMail
> formulaire d'envoi de messages configurables > formulaire d'envoi de messages configurables
## Il gere nativement : ## Il gere nativement :
* Pour
* Cc en meta : **gamumail/mail_cc** - Pour
* Cci en en meta : **gamumail/mail_cci** - Cc en meta : **gamumail/mail_cc**
* Sujet - Cci en en meta : **gamumail/mail_cci**
* Texte - Cci en globals []: `$GLOBALS['gamuza_mail_cci'] = ['sarl.gamuza@gmail.com'];`
* Les documents attachés au modèle (cf ci-dessous) - Sujet
* une liste de pdf (il faut le plugin spipdf) - Texte
![interface](doc/interface.png "interface") - Les documents attachés au modèle (cf ci-dessous)
- une liste de pdf (il faut le plugin spipdf)
![interface](doc/interface.png "interface")
## Il gere des modèles de contenu pour : ## Il gere des modèles de contenu pour :
* Sujet
* Texte - Sujet
* ID documents joints (spip_documents) - 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` - Chaque modèle à un identifiant textuel : **slug** qui doit etre unique. Il ne peut etre créé / modifié QUE par les webmestres
![configuration](doc/configuration.png "Exemple de configuration") - Pour gerer ses modèles, il faut se rendre sur la page : `?page=configuration_mails`
![configuration](doc/configuration.png "Exemple de configuration")
## Personnalisation du formulaire d'envoi ## Personnalisation du formulaire d'envoi
### Dans le html ### 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
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** > **/!\ Le name doit etre Tid_doc**
> >
ex de fichier : > ex de fichier :
```html ```html
<B_doc> <B_doc>
<h2>Fichiers attachés au séjour</h2> <h2>Fichiers attachés au séjour</h2>
@ -43,24 +54,28 @@ ex de fichier :
</div> </div>
</B_doc> </B_doc>
``` ```
3 branchements possibles : 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_debutform.html -> au début du form
* gamumail/SLUG_fichiers.html -> à la fin du formulaire - gamumail/SLUG_soustexte.html -> sous le contenu du mail, avant les pièces jointes
- gamumail/SLUG_fichiers.html -> à la fin du formulaire
### aide à la rédaction du contenu: ### 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** - 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 : 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)
- 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']` - 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` : Exemple dans un fichier `prefixe_fonctions.php` :
```php ```php
$GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture'; $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** - 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 : ### exemple de page d'envoi de mail en choisissant un slug parmi ceux existant :
```html ```html
[(#AUTORISER{modifier,souscripteur,#ENV{id_auteur}}|sinon_interdire_acces)] [(#AUTORISER{modifier,souscripteur,#ENV{id_auteur}}|sinon_interdire_acces)]
@ -76,9 +91,11 @@ $GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture';
``` ```
### Dans le php ### Dans le php
#### 1. Appel du formulaire #### 1. Appel du formulaire
> Args du formulaire : > Args du formulaire :
>
```php ```php
/** /**
* formulaire générique pour envoyer des mails avec pieces attachés * formulaire générique pour envoyer des mails avec pieces attachés
@ -99,100 +116,93 @@ $GLOBALS['remplacements_gamumail']['@@num_facture@@'] = 'numéro de la facture';
function formulaires_gamumail_charger_dist($slug, $auteur = 0, $Tclient = [], $Tpdf = [], $redirect = '', $options = []){ function formulaires_gamumail_charger_dist($slug, $auteur = 0, $Tclient = [], $Tpdf = [], $redirect = '', $options = []){
} }
``` ```
#### argument $slug "no_gamumail" #### argument $slug "no_gamumail"
Si $slug à pour valeur **no_gamumail** alors l'envoi est annulé Si $slug à pour valeur **no_gamumail** alors l'envoi est annulé
Exemple d'option à insérer dans un select sélecteur de slug : Exemple d'option à insérer dans un select sélecteur de slug :
```html ```html
<option value="no_gamumail"[ (#ENV{slug}|=={no_gamumail}|oui) selected="selected"]><:souscriptions:pas_de_mail_auto:></option> <option
value="no_gamumail"
[
(#ENV{slug}|=""
="{no_gamumail}|oui)"
selected="selected"
]
>
<:souscriptions:pas_de_mail_auto:>
</option>
``` ```
#### argument Tclient #### argument Tclient
l'Argument $Tclient est utilisé pour récupérer des emails dans un ou X autres Objets SPIP 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 #### argument Tpdf : attacher des PDF avec contenu dynamique
- exemple d'appel pour 1 fichier PDF avec son contexte : - exemple d'appel pour 1 fichier PDF avec son contexte :
```html ```html
[(#FORMULAIRE_GAMUMAIL{ [(#FORMULAIRE_GAMUMAIL{ #ENV{slug}, #ENV{email}, '', #ARRAY{ fichier,pdf_guide,
#ENV{slug}, nom,Fiche_guide, contexte,#ARRAY{ id_article,#ENV{id_article},
#ENV{email}, type_guide,#ENV{type_guide,guide} } }, #ENV{redirect}, #ARRAY{
'', id_auteur,#ENV{id_auteur} } })]
#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` 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 : - 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 ```html
[(#FORMULAIRE_GAMUMAIL{ [(#FORMULAIRE_GAMUMAIL{ #ENV{slug}, #ENV{email}, '', #ARRAY{ 0,#ARRAY{
#ENV{slug}, fichier,pdf_guide, nom,Fiche_guide, contexte,#ARRAY{
#ENV{email}, id_article,#ENV{id_article}, type_guide,guide, } }, 1,#ARRAY{ fichier,pdf_guide,
'', nom,Fiche_guide_renfort, contexte,#ARRAY{ id_article,#ENV{id_article},
#ARRAY{ type_guide,guide_renfort, } } }, #ENV{redirect}, #ARRAY{
0,#ARRAY{ id_auteur,#ENV{id_auteur} } })]
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 : /!\ 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 - 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. surcharges de chaque étape: charger / vérifier / traiter #### 2. surcharges de chaque étape: charger / vérifier / traiter
Pour chaque étape, on peut modifier l'Array de sortie : Pour chaque étape, on peut modifier l'Array de sortie :
* charger -> $valeurs
* verifier -> $erreurs - charger -> $valeurs
* traiter -> $corps (array du message envoyé à facteur) - verifier -> $erreurs
- traiter -> $corps (array du message envoyé à facteur)
Voir **gamumail_fonctions.php** pour les arguments des fonctions de surcharge + exemples 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 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)
La surcharge pour tous les slugs (`gamumail_tous_...`) précède celle spécifique par slug : on peut donc utiliser les 2 successivement. La surcharge pour tous les slugs (`gamumail_tous_...`) précède celle spécifique par slug : on peut donc utiliser les 2 successivement.
Syntaxe : Syntaxe :
* pour charger pour tous les slugs : **gamumail/tous_charger.php** (fonction `gamumail_tous_charger()`)
* pour charger spécifique d'un slug : **gamumail/NOM_SLUG_charger.php** avec une fonction : - pour charger pour tous les slugs : **gamumail/tous_charger.php** (fonction `gamumail_tous_charger()`)
- pour charger spécifique d'un slug : **gamumail/NOM_SLUG_charger.php** avec une fonction :
```php ```php
function gamumail_NOM_SLUG_charger($valeurs, $options = []){ function gamumail_NOM_SLUG_charger($valeurs, $options = []){
return $valeurs; return $valeurs;
} }
``` ```
* pour verifier pour tous les slugs : **gamumail/tous_verifier.php** (fonction `gamumail_tous_verifier()`)
* pour verifier spécifique d'un slug : **gamumail/NOM_SLUG_verifier.php** avec une fonction : - pour verifier pour tous les slugs : **gamumail/tous_verifier.php** (fonction `gamumail_tous_verifier()`)
- pour verifier spécifique d'un slug : **gamumail/NOM_SLUG_verifier.php** avec une fonction :
```php ```php
function gamumail_NOM_SLUG_verifier($erreurs, $options = []){ function gamumail_NOM_SLUG_verifier($erreurs, $options = []){
return $erreurs; return $erreurs;
} }
``` ```
* pour traiter pour tous les slugs : **gamumail/tous_traiter.php** (fonction `gamumail_tous_traiter()`)
* pour traiter spécifique d'un slug : **gamumail/NOM_SLUG_traiter.php** avec une fonction par ex: - pour traiter pour tous les slugs : **gamumail/tous_traiter.php** (fonction `gamumail_tous_traiter()`)
- pour traiter spécifique d'un slug : **gamumail/NOM_SLUG_traiter.php** avec une fonction par ex:
```php ```php
function gamumail_NOM_SLUG_traiter($corps, $options = []){ function gamumail_NOM_SLUG_traiter($corps, $options = []){
if (array_key_exists('id_article', $options)) { if (array_key_exists('id_article', $options)) {
@ -214,8 +224,11 @@ function gamumail_NOM_SLUG_traiter($corps, $options = []){
return $corps; return $corps;
} }
``` ```
#### 3. Pipeline remplacements_slug pour le traitement du contenu des messages #### 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 : Pour les remplacements des @@ et tout autre traitement du texte des mails on utilisera le pipeline **remplacements_slug** qui utilise les arguments suivants :
```php ```php
* @param array $flux données du pipeline : * @param array $flux données du pipeline :
* $flux['data'] = $html * $flux['data'] = $html
@ -250,27 +263,35 @@ Pour les remplacements des @@ et tout autre traitement du texte des mails on uti
} }
``` ```
#### 4. Pipeline post_gamumail_ok #### 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. 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 #### 5. Ajouter un header / footer dans le content html
on peut définir un header / footer pour les messages : 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/html_header.html => header pour tous les mails
* gamumail/SLUG_html_header.html => pour les mails du modele SLUG - gamumail/html_footer.html => footer pour tous les mails
* gamumail/SLUG_html_footer.html => pour les mails du modele SLUG - 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 #### 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 - 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 - 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` - 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 - 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. 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` => voir le code en commentaire dans le fichier `inclure/fermer_modale`
## API d'envoi de mails utilisant les slugs ## API d'envoi de mails utilisant les slugs
### fonction envoyer_gamumail() ### fonction envoyer_gamumail()
- exemple d'appel : - exemple d'appel :
```php ```php
$fonction = charger_fonction('envoyer_gamumail','inc'); $fonction = charger_fonction('envoyer_gamumail','inc');
$options = [ $options = [
@ -286,7 +307,9 @@ $options = [
]; ];
$fonction(lire_config('souscriptions/slug_souscription_validation'), $Tdest, $options); $fonction(lire_config('souscriptions/slug_souscription_validation'), $Tdest, $options);
``` ```
- arguments : - arguments :
```php ```php
* @param string $slug * @param string $slug
* @param string|array $destinataires = adresses mails et id_auteur séparées par , ou en array * @param string|array $destinataires = adresses mails et id_auteur séparées par , ou en array
@ -304,11 +327,15 @@ $fonction(lire_config('souscriptions/slug_souscription_validation'), $Tdest, $op
``` ```
## Outrepasser l'erreur de certificat auto-signé lors de devs en https local ## Outrepasser l'erreur de certificat auto-signé lors de devs en https local
=> dans le mes_options.php du site mettre : => dans le mes_options.php du site mettre :
``` ```
define('_DEBUG_AUTORISER', true); define('_DEBUG_AUTORISER', true);
``` ```
ce qui permet d'activer les options de curl pour ne pas vérifier le certificat dans *charger_pdf.php* :
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é // pour une connexion https locale avec certificat auto-signé
if (defined('_DEBUG_AUTORISER')) { if (defined('_DEBUG_AUTORISER')) {